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Introduction 


1.1 About This Guide 


Microsoft Windows Programming Tools is divided into two parts: “DOS 
Tools” and “Application Development Tools.” The “DOS Tools” section 
describes programs that perform such actions as compiling and linking 
your application’s source code and debugging and maintaining application 
files. Some of these programs can be run from Windows, but unlike the 
Windows development applications, the DOS tools use command lines and 
parameters for input. “DOS Tools” includes descriptions of the following 
programming tools: 


Program Description 

cl Compiles C-language application source files. 

masm Assembles assembly-language application 
source files. 

rc Compiles application resource files. 

link4 Links the compiled source files for applications. 

symdeb Debugs applications. 

make Maintains assembly- and high-level language pro- 
grams. 

cmacros Creates assembly-language Windows applications that 
are compatible with C and Pascal Windows applica- 
tions. 


Application development tools are used just like other Windows applica- 
tions. They have menus with commands that can be chosen, and they have 
dialog boxes for input. The “Application Development Tools” section 
describes the following programming applications: 


Application Description 

Font Editor Creates fonts for applications. 

Icon Editor Creates cursors, icons, and bitmaps for 
applications. 

Dialog Editor Creates dialog boxes for applications. 

Shaker Shows the effect of memory movement on 
applications. 

Heapwalker Opens the global heap for examination. 
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1.2 Notational Conventions 


The following notational conventions are used throughout this manual: 
Convention Description 


bold Bold type is used to indicate commands, func- 
tions, statements, directives, options, macros, 
registers, data types, structures, and keywords, 
which must be used exactly as shown. In the fol- 
lowing example, —c, ~-AS, —Gsw, —Os, and ~Zdp 
are options of the cl command: 


cl —c —AS —Gsw —Os —Zdp lest.c 


italic Italic is used for placeholders—descriptive names 
that represent parameters, fields, or variables 
that the programmer must supply. In the follow- 
ing example, teat and optionlist are fields which 
must be supplied with specific data that will! be 
passed to the POPUP statement: 


POPUP text optionlist 


[double brackets| Double brackets enclose optional fields or param- 
eters in syntax statements. In the following exam- 
ple, option and ezxecutable-file are optional param- 
eters of the re command: 


re [option] filename [executable-file| 


ellipses... Ellipses following an item indicate that more 
items that have the same form may appear. 
Ellipses may be horizontal or vertical. In the fol- 
lowing example, the ellipses at the end indicate 
that more than one breakaddress may be specified 
for the g command: 


g |==startaddress] [breakaddress]... 


In the following example, the ellipses between the 
lines indicate that intervening program lines 
occur but are not shown: 


acctablename ACCELERATORS 
BEGIN 
event, idvalue, [type] [NOINVERT] [SHIFT] [CONTROL] 


END 


CONTROL+C 
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Keynames appear in small capital letters. A plus 
sign (-+) is used to indicate key combinations. A 

key combination requires that you press and hold 
down the first key and then press the next key(s). 
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2.1 Introduction 


A complete application for the Microsoft Windows presentation manager 
begins with the application’s program and resource source files. You can 
write Windows applications in C, Pascal, or assembly language. You can 
add resources for an application, such as icons, cursors, menus, and dialog 
boxes, by using the Windows resource compiler (rc) described in Chapter 
3, “Resource Compiler: Re.” 


To create a Windows application, you must follow these steps: 


1. Use a text editor to create your application’s C, Pascal, or 
assembly-language source files. 


2. Compile your source files. 


e Use the Microsoft C Compiler to compile any application 
source files written in C. 


e Use the Microsoft Pascal Compiler to compile any application 
source files written in Pascal. 


e Use the Microsoft Macro Assembler to assemble any application 
source files written in assembly language. 


3. Use the development utilities Icon Editor, Font Editor, and Dialog 
Editor to create resources for your application. 


4. Use a text editor to create a resource script file that lists (or 
defines) the resources. The resource script file is described in 
Chapter 3, “Resource Compiler: Rc.” 


5. Use the Windows resource compiler (re) to compile your 
application’s resource script file. 


Once you have completed these steps, you are ready to create a module- 
definition file for your application and to link it. Linking is described in 
Chapter 4, “Windows Linker: Link4.” 


This chapter explains how to create source files for Windows applications 
and how to compile or assemble them. 


2.2 C-Language Applications 


C-language Windows applications are ordinary C-language programs that 
use Windows functions, data types, and programming conventions. You 
compile C-language Windows programs using the Microsoft C Compiler 
and the cl command. All C-language Windows applications must include 
the windows.h file, which contains definitions for all Windows functions, 
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data types, and constants. To include the file, use the # include directive 
at the beginning of each source file. 


Example 


tinclude "“windows.h" 


2.2.1 Small-, Medium-, Compact-, 


and Large-Model Applications 


Windows applications can use the small, medium, compact, or large pro- 
gramming model. You choose a programming model by supplying an 
appropriate option when you compile the application source files. You base 
your choice on your application’s need for data and code. The following 
list describes each programming model and names the compiler option 
used to generate that model: 


Model 
Small 


Medium 


Compact 


Large 


Windows requires that all data segments of compact- and large-model 


Description 


This application has one code segment and one data 
segment. Small-model applications are usually small 
applications that cannot be divided easily into 
separate code segments. Use the —AS option, if 
desired. (The option is not really needed, since the 
compiler generates small-model applications by 


default.) 


This application can have several code segments, but 
only one data segment. Medium-model applications 
are large applications that swap code segments to con- 
serve memory. Use the —AM option. 


This application can have several data segments, but 
only one code segment. Compact-model applications 
typically have a large number of data and a small 

number of program statements. Use the -AC option. 


This application can have several code and data seg- 
ments. A typical large-model application is a large C 
program that uses more than 64 kilobytes of data 
storage. Use the —AL option. 


applications be fixed. This means that the following statement must be in 
the module-definition file of any compact- or large-model application: 


DATA FIXED 
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See Chapter 4, “Windows Linker: Link4,” for information about the 
module-definition file. 


2.2.2 Pascal Calling Conventions 


Windows uses the Pascal calling conventions. Therefore, all functions 
within an application that can be called by Windows must be defined with 
the pascal keyword. The pascal keyword ensures that the C function 
accesses arguments correctly. Functions that can be called by Windows are 
the WinMain function, the application’s window functions, and all call- 
back functions that an application passes to Windows. 


2.2.3 The WinMain Function 


All C-language Windows applications must define a WinMain function. 
This function is the entry point, or starting point, for the application. It 
contains statements and Windows function calls that create windows and 
read and dispatch input intended for the application. The function 
definition has the following form: 


int PASCAL WinMain (hInstance, hPrevInstance, lpCmdLine, nCmdShow) 
HANDLE hinstance; 

HANDLE hPrevinstance:; 

LPSTR lpCmdLine; 

int nCmdShow: 


} 


The WinMain function must be declared with the pascal keyword. 
Although Windows calls the function directly, WinMain must not be 
defined with the far keyword. 


2.2.4 Callback Functions 


Callback functions are functions in an application that Windows calls in 
order to carry out specific tasks. An example is a window function that 
processes messages for an application’s windows. 


Windows expects callback functions to use the Pascal calling conventions, 
so the function must be defined with the pascal keyword. Windows also 
uses far function calls to access callback functions. This means that call- 
back functions in small- and compact-model Windows applications must 
be defined with the far keyword to ensure that the function uses a correct 
return address. The following example shows the form of a callback func- 
tion: | 
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long FAR PASCAL HelloWndProc (hWnd, message, wParam, 1Param) 
HWND hWnd; 

unsigned message? 

WORD wParam: 

LONG 1Param; 


{ 


} 


Callback functions require special code at their beginnings and ends. This 
code, called the Windows prolog and epilog, ensures that the correct data 
segment is used by the function when it executes. To make sure the Win- 
dows prolog and epilog are provided, you must use the —Gw option with 
the cl command when you compile any application source files containing 
functions that can be called with Windows. 


All callback functions must be listed in the EXPORTS statement of the 
application’s module-definition file. This identifies the function as a call- 
back and permits Windows to insert the proper data-segment address in 
the function’s prolog when it loads the application. 


Local functions (functions used exclusively by the application and not 
called by Windows) do not require the Windows prolog and epilog, and 
can use the ordinary C calling conventions. 


2.2.5 Compiling Windows Application 

You compile Windows application source files by using the cl command. 
Since the object files generated by cl must be linked with the Windows 
linker Cae you should use the —e option to prevent cl from attempting 
to create a file that is not executable under Windows. You should give 
other options, such as those specifying programming model, packed struc- 
tures, and Windows prolog and epilog, when the code to be generated 
requires these features. 

Example 

cl -c -AS -Gsw -Os -Zdp test.c 

In this example, the source file test.c is compiled using the recommended 
cl options for a small-model Windows application source file. 

2.2.6 Segment Names 

When compiling medium-, compact-, and large-model source files for 


Windows applications, you must specify the name of the code and data 
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segments to which the given source belongs. You specify the name by 
using the -NT and —ND options. If the options are not used, the C com- 
piler assumes that the source belongs to the standard code and data seg- 


ments, . TEXT and —~ DATA. 


2.2.7 Stack Probes 


Unless the —Gs option is given, the C compiler inserts a stack probe in 
each function. A stack probe is code that checks the stack to make sure 
that it has sufficient space for the local variables declared within the func- 
tion. If the stack would overflow, the code calls the FatalExit function 
and terminates Windows. Stack probes can be used in Windows applica- 
tions and libraries. Since libraries use the stack of the caller, a stack probe 
in a library function checks the caller’s stack. 


2.2.8 Optimizing for Size 


By default, the C compiler optimizes for program speed as it compiles the 
application sources. Since Windows is a multitasking environment and the 
size of an application affects the number of applications that can run at a 
given time, it is better to optimize for size, so you should use the —Os 
option to direct the compiler to optimize for code size instead of speed. 

If you don’t want optimizing, use the —-Od option. 


2.2.9 Source-Level Debugging 


Windows applications written in C are easier to debug if line-number 
information is added to the object file. Line-number information can be 
used by the symbolic debugging utility (symdeb) to display program lines 
from the source file when debugging an application. (For more information 
on symdeb, see Chapter 5, “Symbolic Debugging Utility: Symdeb.”) To 
add line-number information, use the —Zd option. 


2.2.10 Packed Structures 


All Windows functions that use structures use packed structures. A 
packed structure is any structure in which the extra bytes typically used 
by the C compiler for padding have been removed. Windows applications 
that use structures with Windows must use the —Zp option to direct the 
compiler to pack bytes in the structures. 
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2.2.11 Windows and C-Language Libraries 


After your application sources have been compiled, you must link the 
object files with the appropriate C-language libraries for Windows and 
C run-time libraries. The C-language libraries for Windows, slibw.2), 
mlibw.lib, clibw.lib, and Ilibw.lib—contain code for the Windows application 
startup routines and references for the Windows functions. The C run- 
time libraries—slibc.lib, mlibe.lib, clébc.lab, and llibc.lib—contain code for 
routines called by the Windows startup routines and for any C run-time 
functions used by the application. Which C-language libraries you link 
with depends on your application’s programming model. For example, a 
small-model application must be linked with the small-model library 
slibw.b. Although you must use the Windows linker, link4, to link your 
application, the C compiler adds default library information to your 
application’s object files, so the only library you need to specify in the 
link4 command line is the appropriate C-language library for Windows. 
For more information about linking, see Chapter 4, “Windows Linker: 
Link4.” You need an additional library, win87em.lib, when you use the 
coprocessor/emulator floating-point option. 


2.2.12 Environment and Call Arguments 


The startup routines for Windows applications use the _setargv and 
_setenvp functions to copy your application’s command-line arguments 
and the current values of the system’s variables to the __argc, __ argv, 
and environ variables. These variables can be used by any application 
when you supply the following definitions in the application source: 


char *__argv[ ]; 
char x*xenviron: 


int argc; 


The __arge, —— argv, and environ variables actually occupy space in 
your application’s data segment. If your application does not refer to these 
variables, you can prevent —_setargv and _setenvp from allocating this 
space by defining the following functions 1n your application: 


void near _setargv( ) { } 
void near _setenvp( ) { } 


These functions must belong to your application’s _ TEXT segment (the 
p 8 


= code segment if the —NT option is not given in the cl command 
line). 
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After using the __ arge, -__ argv, and environ variables, an application 
can reclaim the space occupied by the variables by using the following 
statements: 


environ = free (environ); 
_argv = free (__argv); 
_arge = 0; 


All Windows applications receive a pointer to the environment allocated 
for the initial load of win200.bin. This means that the __ argv[0] value 
always points to a string that contains win200. bin as the filename of the 
program being run. 


2.2.13 C Run-time Functions 


Windows applications can call C run-time functions to carry out tasks 
such as memory allocation and file input and output. However, since the 
C run-time library was developed for programs running under DOS, not 
Windows, there are some restrictions. 


Windows applications can use any input or output function that does not 
access the system display or keyboard. Input and output functions such as 
fread, fwrite, fclose, fprintf, fscanf, and fgets can be used to read from 
and write to disk files, but should not be used to access the keyboard, 
system display, or communications ports. Functions that access the stan- 
dard input and output files, such as printf and gets, should not be used. 
Although you can use the C run-time input and output functions, a better 
solution is to develop assembly-language routines that provide raw block 
input and output through DOS system calls. No matter how an applica- 
tion accesses disk files, it must not keep disk files open for long periods of 
time, and must be sure to close a disk file before relinquishing control to 
another application. 


Although Windows applications can call C run-time memory-allocation 
functions, such as malloc and calloc, the linker replaces these calls with 
appropriate calls to Windows memory-management functions, such as 
LocalAlloc. Windows memory-management functions are similar but not 
identical to the C run-time functions, so care must be taken when using 
the C run-time functions in your applications. 


2.2.14 Floating-Point Support 


C-language Windows applications that use floating-point variables must 
specify a particular floating-point option during compilation and must 

give additional library names on the link4 command line. The examples 
in the following sections apply to small applications (—AS), but you can 
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C9? 
5 


adapt them to the other programming models by changing the initial 
in certain library names to “c”, “m”, or “I”, as appropriate. See the Micro- 
soft C Compiler User’s Guide for more information about the different 
floating-point libraries and options. (Note that the libraries win87em. lab 
and win87em.exe take the place of em.léb and 87.46, which are used in the 
DOS environment.) 


2.2.14.1 Coprocessor/Emulator Math Option 


You can choose the coprocessor/emulator math option by specifying —FP1 
and —FPc on the compiler command line and by linking with slbfw%b and 
win87em.lib on the link4 command line. siibce Lib 


Example 


cl -c -FPi -AS -Gsw -Os -Zpe sample.c 
link4 sample, /align:16, /map, win87em slibw,sample.def; 


If you link the application with win87em.lib, you can run the application 
either with or without a numeric coprocessor (8087 /80827 /80387). If there 
is a coprocessor present, the application uses it; if there 1s no coprocessor 
present, the application’s floating-point emulator simulates the operation 
of the coprocessor. To use the coprocessor/emulator option, you must 
have the dynamic-link library win87em.eze either in the current directory 
or along the executable search path when the application is loaded. (The 
application developer should distribute the win87em.ezre library with appli- 
oo that use it.) This is a fast option when there is a coprocessor avail- 
able. 


2.2.14.2 Alternate Math Option 

You can choose the alternate math option by specifying -FPa on the 
compiler command line and by linking with slibw.tvb on the link4 com- 
mand line. 

Example 


cl -c -FPa -AS -Gsw -Os -Zpe sample.c 
link4 sample, /align:16,/map,slibw,sample.def; 


This option does not use the coprocessor to perform floating-point opera- 


tions. It is faster than the emulator when no coprocessor is present, but 
slower than the coprocessor math option when the coprocessor is present. 
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2.2.15 Windows Libraries 


Windows libraries written in C have slightly different requirements than 
do Windows applications written in C. Unlike Windows applications, Win- 
dows libraries are not executable programs; that is, although a library is 
loaded, it does not run. Instead, the code in a library is made available to 
all applications that need to use it, and an application can execute a por- 
tion of the library by calling one of the exported functions in the library. 
Since a Windows library is not a program, it must not have a WinMain 
function. No entry point is required unless the library must carry out some 
initial task such as initializing a local heap. If an entry point is required, 
the hbrary must define its own. Information about the entry point and the 
parameters passed to it can be found in the Microsoft Windows Program- 
mer’s Learning Guide. 


Exported functions in Windows libraries must have the same attributes as 
callback functions in Windows applications. The function must use the far 
keyword. Although the Pascal calling convention is optional, it is strongly 
recommended in order to remain consistent with the Windows interface. 
Exported functions must have the Windows prolog and epilog, so the -Gw 
option is required. Exported functions must be listed in the library’s 
module-definition file. 


Since Windows libraries do not use the same startup routine, they should 
be linked with the C-language libraries for Windows libraries (swinlibc. lib, 
mwintibe.lib, cwinlibe.lib, and dwinlibc.lib) instead of the libraries for Win- 
dows applications. These libraries contain references to the Windows ker- 
nel functions and to the C run-time functions only. It is assumed that a 
Windows library does not require access to Windows user or GDI func- 
tions. If a library does require access to those functions, it can be linked 
with slzbw.lib, mltbw.lib, clebw.lb, or llibw.lib, as appropriate; however, this 
library must be specified after the corresponding winlibc.lib file on the 
link4 command line. 


Windows libraries always use the stack of the calling application for 
parameters and local variables. This means that the values of the ds and 
ss registers are not equal when the library is executed. Since the C com- 
piler generates code that assumes that the ds and ss registers are equal, 
Windows libraries may fail unless compiled with the —Aw option. This 
option directs the compiler to generate code that does not assume that the 
registers are equal. The following example shows the recommended options 
for compiling Windows libraries: 


cl -c -Aw -As -An -Os -Zdp testlib.c 
In this example, the —As and —An options are used to complete the pro- 


gramming model specification, since the -AS option cannot be used with 
the —Aw option. 
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Code sharing also restricts which C run-time functions a library can use. 
Windows libraries must not call C run-time functions that assume that ds 
and ss are equal. Appendix B, “C Run-time Functions,” contains a list of 
functions that indicates which functions can and cannot be used by Win- 
dows libraries. 

Since Windows libraries use the stack of the caller and cannot determine 
the size of that stack, functions should not declare exceptionally large 
local variables. Large variables should be declared as static variables 
within the library’s own data segment. 


To avoid problems in Windows libraries that use pointers, either by gen- 
erating their own or by receiving them from applications, you should use 
the following guidelines: 


e Always cast pointers to full 32-bit segment:offset addresses. The 
windows.h file contains a variety of type definitions that can be 
used to cast pointers. 


e Use the —Aw option when you compile to ensure that pointers 
receive their proper segment address when cast to 32-bit addresses. 


e Make sure functions that receive pointers from an application or 
from other functions within the library receive long pointers. 


2.3. Pascal-Language Applications 


Pascal-language Windows applications are ordinary Pascal-language pro- 
grams that use Windows functions, data types, and programming conven- 
tions. You compile Pascal-language Windows programs using the Micro- 
soft Pascal Compiler. 


For information on using Pascal-language Windows applications, see the 
Microsoft Pascal Compiler Version 4.0 Update. 


2.4 Assembly-Language Applications 


Assembly-language Windows applications are highly structured assembly- 
language programs that use high-level-language calling conventions as 
well as Windows functions, data types, and programming conventions. 
Although you assemble assembly-language Windows programs using the 
Microsoft Macro Assembler, the goal is to generate object files that are 
similar to object files generated using the C compiler. The following is a 
list of guidelines designed to help you meet this goal and create assembly- 
language Windows applications: 
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Include the emacros.inc file in the application source files. This file 
contains high-level-language macros that define the segments, pro- 
gramming models, function interfaces, and data types needed to 
create Windows applications. For a complete description of the C 
macros, see Chapter 7, “Assembly-Language Macros.” 


Define the programming model, setting one of the options memS, 
memM, memC, or memL to 1. This option must be set before 
you specify the statement that includes the cmacros.ine file. 


Set the calling convention to Pascal by setting the PPLM option 
to 1. This option must be set before you specify the statement 
that includes the cmacros.inc file. Pascal calling conventions are 
required only for functions that are called by Windows. 


Create the application entry point, WinMain, and make sure that 
it is declared a public function. It should have the following form: 


cProc WinMain, <PUBLIC>, <si,di> 
parmW hInstance 
parmW hPrevInstance 
parmD lpCmdLine 
parmW nCmdShow 
cBegin WinMain 


cEnd WinMain 


sEnd 


The WinMain function should be defined within the standard 
code segment CODE. 


Set the Windows prolog and epilog option ?WIN to 1. This option 
must be set before you specify the statement that includes the 
cmacros.inc file. This option is required only for callback functions 
(or for exported functions in Windows libraries). 


Make sure that your callback functions are declared 


cProc TestWndProc, <FAR,PUBLIC>, <si,di> 
parmwW hWnd 
parmW message 
parmW wParam 
parmD 1Param 
cBegin TestWndProc 


cEnd TestWndProc 
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a2 


Callback functions must be defined within a code segment. 


Link your application with the appropriate C-language library for 
Windows and C run-time libraries. To link properly, you may need 
to add an external definition for the absolute symbol __ acrtused 
in your application source file. 


POO rg 
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3.1 Introduction 


Applications for the Microsoft Windows presentation manager typically 
use a variety of resources, such as icons, cursors, menus, and dialog boxes. 
These resources must be created and then defined in a file called the 
resource script file. The resource script file defines the names and attri- 
butes of the resources to be added to the application’s executable file. The 
file consists of one or more “resource statements” that define the resource 
type and original file. 


This chapter describes how to create a resource script file and how to com- 
pile your application’s resources. 


3.2 Building the Resource Script File 


To define the resources for the application, you must create the resource 
script file. (You can create the script file by using an ordinary text editor.) 
The resource script file consists of one or more resource statements that 
define the resource’s name, type, and details. 


The file also contains one or more directives, which are special statements 
that define actions to be performed on the script file before it is compiled. 
Resource directives can assign values to names, include the contents of 
files, and control compilation of the script file. The resource directives are 
identical to the directives used in the C programming language. 


The resource script file has the extension .re. 
The following is a list of the resource statements: 
Type of Statement Statement 


Single-line statements CURSOR 
ICON 
BITMAP 
FONT 


User-defined resources User-supplied 


Multiple-line statements RCDATA 
STRINGTABLE 
ACCELERATORS 
MENU 
DIALOG 
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Directives # include 


Example 


#include “shapes.h" 
shapes cursor shapes.cur 


shapes icon shapes.ico 
shapes menu 
begin 
pop-up "“&Shape"™ 
begin 


menuitem "&Clear™, CLEAR 
menuitem "&Rectangle", TRECT 
menuitem "&Triangle", TRIANGLE 
menuitem "&Star", STAR 
menuitem "&Ellipse", ELLIPSE 
end 
end 


In this example, the script file defines the resources for an application 
called “Shapes.” The cursor, icon, and menu keywords specify the type 
of resource being described. The name of the resource appears on the left. 
The file containing the resource appears on the right. If the resource is 
defined in the script file (as is the menu resource, above), its definition fol- 
lows the keyword and is enclosed in the keywords begin and end. 


You are free to choose any names you like for the resources. However, the 
names must be letters and digits. You will use these names in your appli- 
cation to identify the resource you want to load. You can place several 
resources of the same type in a resource file, but no two resources of the 
same type can have the same name. 
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3.2.1 Directives in a Resource Script 


The resource directives are special statements that define actions to be 
performed on the script file before it is compiled. The directives can assign 
values to names, include the contents of files, and control compilation of 
the script file. 


The resource directives are identical to the directives used in the C pro- 
gramming language. They are fully defined in the Microsoft C' Reference 
Manual. 


The script file can contain any number of the following directives: 


# define # ifdef 
# elif # ifndef 
# else # include 
uf endif # undef 

j 


When you use directives, the number sign (#) must appear in the first 
column of the line. 


3.2.2 Using the #include Directive 


Although resource statements and directives can be in any order in the 
resource script file, the # include directive has a slightly different action 
depending on what statements are placed before it. If an # include direc- 
tive is placed before the first definition statement, the Windows resource 
compiler (re) processes only the # define statements in the specified 
include file. If the # include directive is placed after the first definition 
statement, re processes all statements in the include file. For example, in 
the following resource script file only the # define statements in the files 
windows.h and mydefs.h are processed. Other statements in these files are 
ignored. But all statements in the file dlgs.rc are processed. 


#include "windows.h" 
#include “mydefs.h"™ 
myicon icon myicon.ico 


#include "“dlgs.rc” 
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3.2.3 Using the Rcinclude Keyword 


Syntax 
rcinclude filename 


This keyword copies the contents of the file specified by filename into your 
resource script before re processes the script. The rcinclude keyword 
differs from the #include directive in one important aspect: nothing in 
the file designated by rcinclude is ignored. In a file named by # include, 
anything other than definitions a define statements) is ignored when the 
file is processed. Thus, you should use rcinclude, not # include, to put 
resources in files that you will name. 


The filename field specifies an ASCII string, enclosed in double quotation 
marks, that identifies the DOS filename of the file to be included. A full 
pathname must be given if the file is not in the current directory or in the 
directory specified by the INCLUDE environment variable. The filename 
field is handled as a C string: two backslashes must be given wherever one 
is expected in the pathname (for example, “root\\sub”). A single forward 
slash (/) can be used instead of double backslashes (for example, 

“root /sub” ). 


Example 


#include "style.h" 
hand icon hand.ico 
name menu 
begin 
rcinclude menu.rc 
end 


In this example, the menu.rc file contains the following: 


menuitem “&Pause", IDOK 


3.3. Compiling Resources 


You can compile your application’s resources by using the Windows 
resource compiler, re. The compiler reads a script file that contains a list 
of the resources you wish to compile and add to the resource file. The com- 
piler automatically places the resources in the application’s resource file 
after compiling them. 
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Syntax 

re [option] filename [erecutable-file] 

The option parameter allows the selection of one of the following options: 
Option Description 


—r Directs re to compile the resource file, then saves 
the result in a special binary resource file having 
the filename extension .res. When —r is specified, 
rc does not copy the compiled resource to the 
executable file. 


—LIM32 Sets re to compile an application that uses 
expanded memory according to the Lotus Intel 
Microsoft Expanded Memory Specification, 
Version 3.2. 


—multinst Sets rec to compile an application that uses 
expanded memory so that multiple instances of 
the application will use different EMS banks. 


The filename parameter specifies the name of the script file that contains 
the names, types, filenames, and descriptions of the resources you want to 
add to the file. 

The executable-file parameter specifies the name of the executable file to 


put the resources into. If no executable file is given, the executable file 
having the same name as the script file is used. 


Example 


re sample.rc 
re sample 


Both of the commands in the example read the resource script file 
sample.rc, create a compiled resource file sample.res, and copy the re- 
sources to the executable file sample.eve. When a filename has no exten- 
sion, .rc 1S assumed. 


The following command creates the compiled resource file sample.res: 


re -r sample.rc 


When -r is specified, re does not copy the compiled resource to the execut- 


able file. 
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The following command searches the current directory for the compiled 
file sample.res. If the file is found, it copies the resources in it to the exe- 
cutable file sample.eze. If no .res file is found, re terminates without 
searching for a resource script file. 


re sample.res 


The following command compiles the script file sample.re and copies the 
result to the executable file run. exe: 


re sample run.exe 


3.4 Single-Line Statements 


The single-line statements define resources that are contained in a single 
file, such as cursors, icons, and fonts. The statements associate the file- 
name of the resource with an identifying name or number. The resource 1s 
added to the executable file when the application is created, and can be 
extracted during execution by referring to the name or number. 


The following is the general form for all single-line statements: 

namelD resource-type |load-option| |mem-option| filename 

The namelD field specifies either a unique name or an integer value identi- 
fying the resource. For a font resource, namelD must be a number; it can- 


not be a name. 


The resource-type field specifies one of the following keywords, which iden- 
tify the type of resource to be loaded: 


Keyword Resource Type 

CURSOR Specifies a bitmap that defines the shape of the 
mouse cursor on the display screen. 

ICON | Specifies a bitmap that defines the shape of the 
icon to be used for a given application. 

BITMAP Specifies a custom bitmap that an application is 
going to use in its screen display or as an item in 
a, menu. 

FONT Specifies a file that contains a font. 
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The load-option field takes an optional keyword that specifies when the 
resource is to be loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately. 
LOADONCALL Resource is loaded when called. 

The default is LOADONCALL. 

The optional mem-option field takes the following keyword or keywords, 


which specify whether the resource is fixed or movable and whether it is 
discardable: 


FIXED Resource remains at a fixed memory location. 
MOVEABLE Resource can be moved if necessary to compact 
memory. 


DISCARDABLE Resource can be discarded if no longer needed. 


The default is MOVEABLE and DISCARDABLE for cursor, icon, and 
font resources. The default for bitmap resources is MOVEABLE. 


The filename field takes an ASCII string that specifies the DOS filename of 
the file containing the resource. A full pathname must be given if the file is 
not in the current working directory. 


Examples 


cursor CURSOR point.cur 
cursor CURSOR DISCARDABLE point.cur 
10 CURSOR custom.cur 


desk ILCON desk.ico 

desk ICON DISCARDABLE desk.ico 
Li ICON custom.ico 

disk BITMAP disk.bmp 

disk BITMAP DISCARDABLE disk.bmp 
12 BITMAP custom.bmp 


S FONT CMROMAN.FON 
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3.5 User-Defined Resources 


An application can also define its own resource. The resource can be any 
data that the application intends to use. A user-defined resource statement 
has the following form: 


namelD typelD [load- option] [mem-option] filename 


The namelD field specifies either a unique name or an integer value identi- 
fying the resource. 


The typelD field specifies either a unique name or an integer value identify- 
ing the resource type. If a number is given, it must be greater than 255. 
The numbers 1 through 255 are reserved for existing and future predefined 
resource types. 


The load-option field takes an optional keyword that specifies when the 
resource is to be loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately. 
LOADONCALL Resource is loaded when called. 

The default is LOADONCALL. 

The optional mem-option field takes the following keyword or keywords, 


which specify whether the resource is fixed or movable and whether it is 
discardable: 


FIXED Resource remains at a fixed memory location. 
MOVEABLE Resource can be moved if necessary to compact 
memory. 


DISCARDABLE Resource can be discarded if no longer needed. 
The default is MOVEABLE. 

The filename field takes an ASCII string specifying the DOS filename of 
the file containing the resource. A full pathname must be given if the file 
is not in the current working directory. 


Example 


array MYRES data.res 
14 300 custom.res 
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3.6 RCDATA Statement 


Syntax 


RCDATA [load-option] | mem-option|] 
BEGIN 
raw-data 


END 


The RCDATA statement defines one or more more raw data resources 
for an application. Raw data resources permit the inclusion of binary data 
directly into the executable file. 


The load-option field takes an optional keyword that specifies when the 
resource is to be loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately. 
LOADONCALL Resource is loaded when called. 

The default is LOADONCALL. 

The optional mem-option field takes the following keyword or keywords, 


which specify whether the resource is fixed or movable and whether it is 
discardable: 


FIXED Resource remains at a fixed memory location. 
MOVEABLE Resource can be moved if necessary to compact 
memory. 


DISCARDABLE Resource can be discarded if no longer needed. 
The default is MOVEABLE and DISCARDABLE. 
The raw-data field specifies one or more integers and strings stated in 


standard C-language format. Integers are given in decimal, octal, or 
hexadecimal format. 


Example 


resname RCDATA 
BEGIN 


"Here is a data string\O", /* A string. Note: not null-terminated */ 

1024, /* int & / 

0x029a, /* hex int */ 

00733, /* octal int */ 

"\O7" /* octal byte ars 
END 
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3.7 STRINGTABLE Statement 


Syntax 


STRINGTABLE [load-option] [mem-option| 
BEGIN 
string-definitions 


END 


The STRINGTABLE statement defines one or more more string 
resources for an application. String resources are simply null-terminated 
ASCII strings that can be loaded when needed from the executable file, 
using the LoadString function. 


The load-option field takes an optional keyword that specifies when the 
resource is to be loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately. 
LOADONCALL Resource is loaded when called. 

The default is LOADONCALL. 

The optional mem-option field takes the following keyword or keywords, 


which specify whether the resource is fixed or movable and whether it is 
discardable: 


FIXED Resource remains at a fixed memory location. 
MOVEABLE Resource can be moved if necessary to compact 
memory. 


DISCARDABLE Resource can be discarded if no longer needed. 
The default is MOVEABLE and DISCARDABLE. 
The string-definitions field specifies one or more ASCII strings, enclosed in 


double quotation marks and preceded by an identifier. The identifier must 
be an integer. 
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Example 


tdefine IDS HELLO 1 
#define IDS_GOODBYE 2 


STRINGTABLE 
BEGIN 
IDS_HELLO, "Hello" 
IDS_GOODBYE, "Goodbye" 
END 


3.8 ACCELERATORS Statement 


Syntax 


acctablename ACCELERATORS 
BEGIN 
event, tdvalue, |typel [NOINVERT], [SHIFT] CONTROL] 


END | 
The ACCELERATORS statement defines one or more accelerators for 
an application. An accelerator is a keystroke defined by the application to 


give the user a quick way to perform a task. The TranslateAccelerator 
function is used to translate accelerator messages from the application 


queue into WM_ COMMAND or WM. SYSCOMMAND messages. 
The acctablename field specifies the name of the accelerator table. 


The event field specifies the keystroke to be used as an accelerator. It can 
be any one of the following: 


Character Description 
"char" A single character enclosed in double quotes. 


The character can be preceded by a caret 
(*), meaning that the character is a control 


character. 
ASCII character An integer value representing an ASCII 
character. The type field must be ASCII. 
Virtual key character An integer value representing a virtual key. 


The type field must be VIRTKEY. 
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The idvalue field specifies an integer value that identifies the accelerator. 


The type field is required only when event is an ASCII character or a vir- 
tual key character. The type field specifies either ASCH or VIRTKEY; 
the integer value of event is interpreted accordingly. 


The NOINVERT option, if given, means that no top-level menu item 

is highlighted when the accelerator is used. This is useful when defining 
accelerators for actions such as scrolling that do not correspond to a menu 
item. If NOINVERT is omitted, a top-level menu item will be high- 
lighted (if possible) when the accelerator is used. 


The SHIFT option, if given, causes the accelerator to be activated only if 
the SHIFT key is down. 


The CONTROL option, if given, defines the character as a control char- 
acter (the accelerator is only activated if the CONTROL key is down). This 
has the same effect as using a caret (“) before the accelerator character in 
the event field. 


Kxamples 


MainAce ACCELERATORS 


BEGIN 
tas ID SAVE, NOINVERT 
VK_UP, 6, VIRTKEY, NOINVERT 
7, ID_BELL, ASCII 
Wag" ID BELL 
"G") ID BELL, CONTROL 

END 


Note that the last three definitions are equivalent. 


3.9 MENU Statement 


Syntax 


menulD MENU |load-option] |mem-option| 
BEGIN 
item-definitions 


END ee 


The MENU statement defines the contents of a menu resource. A menu 
resource is a collection of information that defines the appearance and 
function of an application menu. A menu is a special input tool that lets 
a user select commands from a list of command names. 
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The menulD field specifies a name or number used to identify the menu 
resource. 


The load-option field takes an optional keyword that specifies when the 
resource is to be loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately. 
LOADONCALL Resource is loaded when called. 

The default is LOADONCALL. 

The optional mem-option field takes the following keyword or keywords, 


which specify whether the resource is fixed or movable and whether it is 
discardable: | 


FIXED Resource remains at a fixed memory location. 
MOVEABLE Resource can be moved if necessary to compact 
memory. 


DISCARDABLE Resource can be discarded if no longer needed. 


The ttem-definition field specifies special resource statements which define 
the items in the menu. 


Example 
The following is an example of a complete MENU statement. 


sample MENU 
BEGIN 
Menuitem "&Alpha", 100 
POPUP "&Beta" 
BEGIN 
Menuitem "&Item 1", 200 
MENUITEM "I&tem 2", 201, CHECKED 
END 
END 


3.9.1 Item-Definition Statements 
The MENUITEM and POPUP statements are used in the ztem- 


definition section of a MENU statement to define the names and attri- 
butes of the actual menu items. Any number of statements can be given; 
each defines a unique item. The order of the statements defines the order 
of the menu items. 


The MENUITEM and POPUP statements can only be used within an 
item-definition section of a MENU statement. 
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3.9.1.1 MENUITEM Statement 


Syntax 
MENUITEM text, result, optronlist 
This optional statement defines a menu item. 


The tezt field takes an ASCII string, enclosed in double quotation marks, 
which specifies the name of the menu item. 


The string can contain the escape characters \t and \a. The \t character 
inserts a tab in the string and is used to align text in columns. Tab charac- 
ters should be used only in pop-up menus, not in menu bars. (See Section 
3.9.1.2 for information on pop-up menus.) The \a character sets all text 
that follows it flush right. 


To insert a double quotation mark (") in the string, use two double quota- 
tion marks ("" 


To add a mnemonic to the text string, place the ampersand (&) ahead of 
the letter that will be the mnemonic. This will cause the letter to appear 
underlined in the control and to function as the mnemonic. To use the 
ampersand as a character in a string, insert two ampersands (&&). 


The result field takes an integer value that specifies the result generated 
when the user selects the menu item. Menu-item results are always inte- 
gers; when the user clicks the menu-item name, the result is sent to the 
window that owns the menu. 


The optioniist field takes one or more predefined menu options, separated 
by commas or spaces, that specify the appearance of the menu item. The 
menu options are as follows: 


Option Description 

MENUBREAK Item is immediately preceded by a new line. 

CHECKED Item has a checkmark next to it. 

INACTIVE Item name is displayed, but cannot be selected. 

GRAYED Item name is initially inactive and appears on the 
menu in gray or a lightened shade of the menu- 
text color. 

HELP Item is flush right on the menu bar, with a verti- 


cal separator to its left. The Help item cannot be 
selected from the keyboard. 
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The INACTIVE and GRAYED options cannot be used together. 


Examples 


MENUITEM "&Alpha", 1, CHECKED, GRAYED 
MENUITEM "&Beta", 2 


3.9.1.2 POPUP Statement 


Syntax 


POPUP text, optionlist 
BEGIN 
item-definitions 

END 


This statement marks the beginning of a pop-up menu definition. A pop- 
up menu (which is also known as a drop-down menu) is a special menu 
item that displays a sublist of menu items when it is selected. 


The teat field takes an ASCII string, enclosed in double quotation marks, 
which specifies the name of the pop-up. 


The optionlist field takes one or more predefined menu options that specify 
the appearance of the menu item. The menu options are as follows: 


Option Description 


MENUBREAK Item is placed in a new column. 
MENUBARBREAK __ Item is placed in a new column. The old and 


new columns are separated with a bar. 


CHECKED Item has a checkmark next to it. 
INACTIVE Item name is displayed, but cannot be selected. 
GRAYED Item name is initially inactive and appears on 


the menu in gray or a lightened shade of the 
menu-text color. 


The options can be combined using the bitwise OR operator. The IN- 
ACTIVE and GRAYED options cannot be used together. 


The ztem-definitions field can specify any number of MENUITEM state- 
ments. POPUP statements in a pop-up menu are not allowed. 


39 


Microsoft Windows Programming Tools 


Example 


chem MENU 
BEGIN 


POPUP "“&Elements" ao 
BEGIN 

Menuitem "&Oxygen", 200 

Menuitem "&Carbon", 201, CHECKED 

Menuitem "&Hydrogen", 202 


END 

POPUP "&Compounds", CHECKED 

BEGIN 
Menuitem "&Glucose™, 301 
Menuitem "&Sucrose", 302, CHECKED 
Menuitem "&Lactose", 303, MENUBREAK 
Menuitem "&Fructose", 304 

END 

END 


3.9.1.3 MENUITEM SEPARATOR Statement 


Syntax 

MENUITEM SEPARATOR 

This special form of the MENUITEM statement creates an inactive 
menu item that serves as a dividing bar between two active menu items. 
In pop-up menus, the bar is horizontal. In a menu bar, the dividing bar 
is vertical. 


Example 


MENUITEM “&Roman", 206 
MENUITEM SEPARATOR 
MENUITEM "&20 Point", 301 


3.10 DIALOG Statement 


The DIALOG statement defines a template that can be used by an appli- 
cation to create dialog boxes. 
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Syntax 


namelD DIALOG |load-option] [mem-option|] 2, y, width, height 
| option-statements] 
BEGIN 


control-statements 


END 


This statement marks the beginning of a DIALOG template. It defines 
the name of the dialog box, the memory and load options, the box’s start- 
ing location on the display screen, and its width and height. 


The namelD field specifies either a unique name or an integer value that 
identifies the resource. 


The load-option field takes an optional keyword that specifies when the 
resource is to be loaded. It must be one of the following: 


PRELOAD Resource is loaded immediately. 
LOADONCALL Resource is loaded when called. 

The default is LOADONCALL. 

The optional mem-option field takes the following keyword or keywords, 


which specify whether the resource is fixed or movable and whether it is 
discardable: 


FIXED Resource remains at a fixed memory location. 
MOVEABLE Resource can be moved if necessary to compact 
memory. 


DISCARDABLE Resource can be discarded if no longer needed. 
The default is MOVEABLE. 


The x and y fields take integer values that specify the z and y coordinates 
of the upper-left corner of the dialog box. The exact meaning of the coor- 

dinates depends on the style defined by the STYLE statement. For child- 
style dialog boxes, the coordinates are relative to the origin of the parent 

window, unless the dialog box has the style DS_ ABSALIGN,; in that case 

the coordinates are relative to the origin of the display screen. 


The width and height fields take integer values that specify the width and 


height of the box. The width units are 1/4 of the width of a character; the 
height units are 1/8 of the height of a character. 
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The option and control statements are described in the following sections. 


Example 
errmess DIALOG 10, 10, 300, 200 
The following is a complete example of a DIALOG statement. 


#include "windows.h" 


errmess DIALOG 10, 10, 300, 110 
STYLE WS_POPUP !WS_BORDER 
CAPTION "Error!" 


BEGIN 
CTEXT "Select One:", 1, 10, 10, 280, 12 
RADIOBUTTON "&Retry", 2, 75, 30, 60, 12 
RADIOBUTTON “&Abort", 3, 75, 50, 60, 12 
RADIOBUTTON "&Ignore", 4, 75, 80, 60, 12 

END 

Comments 


Do not use the WS_ CHILD style with a modal dialog box. The Dialog- 
Box function always disables the parent /owner of the newly-created dia- 
log box. When a parent window is disabled, its child windows are impli- 
citly disabled. Since the parent window of the child-style dialog box is dis- 
abled, so is the child-style dialog box itself. 


If a dialog box has the DS. ABSALIGN style, the dialog coordinates for its 
upper-left corner are relative to the screen origin instead of to the upper- 
left corner of the parent window. You would typically use this style when 
you want the dialog box to start in a specific part of the display no matter 
where the parent window may be on the screen. 


The name DIALOG can also be used as the class-name parameter to the 


CreateWindow function in order to create a window with dialog-box 
attributes. 
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3.10.1 Dialog Option Statements 


The dialog option statements, given in the option-statements section of the 
DIALOG statement, define special attributes of the dialog box, such as 
its style, caption, and menu. The option statements are optional. If there 
are no option statements, the dialog box is given a default attribute. Dia- 
log option statements include the following: 


e STYLE 
e CAPTION 
e MENU 
e CLASS 


The option statements are discussed individually in the following sections. 
3.10.1.1 STYLE Statement 


Syntax 
STYLE style 


This optional statement defines the window style of the dialog box. The 
window style specifies whether the box is a pop-up or a child window. 
The default style has the following attributes: 


Ws. POPUP 
WS-— BORDER 
Ws. SYSMENU 


The style field takes an integer value or predefined name that specifies the 
window style. It can be any of the window styles defined in the following 
Table 3.1. 


mee DS. SYSMODAL can also be used to create a system modal dia- 
log box. 


Comments 


If the predefined names are used, the include directive must be used 
so that the windows.h file will be included in the resource script. 
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Table 3.1 
Window Styles 


Style 


Meaning 


W5_ GROUP 


WS_ TABSTOP 


WS_ POPUP 

Ws_ CHILD 

WS_ ICONIC 

WS_ OVERLAPPED 

WS_ OVERLAPPEDWINDOW 


WS_ MINIMIZE 
WS. MAXIMIZE 
WS_ BORDER 
Ws... CAPTION 


Ws_ DLGFRAME 


Ws_ SYSMENU 


WS- MINIMIZEBOX 
Ws-— MAXIMIZEBOX 
WS SIZEBOX 
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Specifies the first control of a group of controls 
in which the user can move from one control to 
the next by using the cursor keys. All controls 
defined with the WS_ GROUP style after the 
first control belong to the same group. The 
next control with the WS_ GROUP style ends 
the style group and starts the next group (i.e., 
one group ends where the next begins). 


Specifies one of any number of controls 
through which the user can move by using the 
TAB key. The TAB key moves the user to the 
next control specified by the WS_ TABSTOP 


style. 
Creates a pop-up window. Cannot be used 


with WS_. CHILD. 


Creates a child window. Cannot be used with 


WS... POPUP 


Creates a window that is initially iconic. For 


use with WS. OVERLAPPED only. 
Creates an overlapping window. 
Creates an overlapped window having the 


styles WS_ OVERLAPPED, WS_ CAPTION, 
WS_SYSMENU, and WS_ SIZEBOX. 


Creates a window of minimum size. 
Creates a window of maximum size. 
Creates a window that has a border. 


Creates a window that has a title bar (implies 
WS_ BORDER 


ial a window with a double border but no 
title. 


Creates a window that has a system-menu box 
in its title bar. Used only for windows with 
title bars. If used with a child window, this 
style creates a Close box instead of a system- 
menu box. 


Creates a window that has a Minimize box. 
Creates a window that has a Maximize box. 


Creates a window that has a Size box. Used 
only for windows with a title bar or with 
vertical and horizontal scroll bars. 
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Table 3.1 (continued) 


Style Meaning 
WS_ VSCROLL Creates a window that has a vertical scroll bar. 
WS. HSCROLL Creates a window that has a horizontal scroll bar. 


WS_ CLIPCHILDREN Excludes the area occupied by child windows when 
drawing within the parent window. Used when creating 
the parent window. 


WS. CLIPSIBLINGS Clips child windows relative to each other; that is, 
when a particular child window receives a WP_ PAINT 
message, this style clips all other top-level child 
windows out of the region of the child window to be 
updated. (If WS_ CLIPSIBLINGS is not given and 
child windows overlap, it is possible, when drawing in 
the client area of a child window, to draw in the client 
area of a neighboring child window.) For use with 
WS. CHILD only. 


WS- VISIBLE Creates a window that is initially visible. This applies 
to overlapping and pop-up windows. For overlapping 
windows, the y parameter is used as a Show Window 
function parameter. 


Ws_ DISABLED Creates a window that is initially disabled. 


WS POPUPWINDOW _ Creates a pop-up window that has the styles 
WS_ POPUP, WS_ BORDER, and WS. SYSMENU. 


Ws_ CHILDWINDOW Creates a child window that has the style WS_ CHILD. 


3.10.1.2 CAPTION Statement 


Syntax 
CAPTION captiontezt 


This optional statement defines the dialog box’s title. The title appears in 
the box’s caption bar (if it has one). 


The default caption is empty. 

The captiontezt field specifies an ASCII character string enclosed in double 
quotation marks. 

Example 


CAPTION "Error!" 
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3.10.1.3 MENU Statement 


Syntax 
MENU menuname aa 


This optional statement defines the dialog box’s menu. If no statement is 
given, the dialog box has no menu. 


The menuname field specifies the resource name or number of the menu 
to be used. 
Example 


MENU errmenu 
3.10.1.4 CLASS Statement 


Syntax 
CLASS class 


This optional statement defines the class of the dialog box. If no statement 
is given, the predefined dialog class will be used as the default. 


The class field specifies an integer or a string, enclosed in double quotation 
marks, that identifies the class of the dialog box. 
Example 


CLASS "myclass" 


Comments 


The CLASS statement should be used with special cases, since it over- 
rides the normal processing of a dialog box. The CLASS statement con- 
verts a dialog box to a window of the specified class; depending on the 
class, this may give undesirable results. Do not use the predefined control oe 
class names with this statement. 
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3.10.2 Dialog Control Statements 


The dialog control statements, given in the control-statements section of 
the DIALOG statement, define the attributes of the control windows that 
appear in the dialog box. A dialog box is empty unless one or more control 
statements are given. Control statements include the following: 


e LTEXT 
e RTEXT 
e CTEXT 


e CHECKBOX 

e PUSHBUTTON 

e LISTBOX 

e GROUPBOX 

e DEFPUSHBUTTON 
e RADIOBUTTON 


e EDITTEXT 
e ICON 
e CONTROL 


The control statements are discussed individually in the following sections. 
For more information on control classes and styles, see Tables 3.2 and 3.3. 


3.10.2.1 LTEXT Statement 


Syntax 
LTEXT tect, id, x, y, width, height, [style] 


This statement defines a flush-left text control. It creates a simple rectan- 
gle that displays the given text flush-left in the rectangle. The text is for- 
matted before it 1s displayed. Words that would extend past the end of a 
line are automatically wrapped to the beginning of the next line. 


The ¢tezt field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 
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The 2d field takes a unique integer value that identifies the control. 


The zand y fields take integer values that specify the z and y coordinates 
of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 


The width and height fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field contains WS_TABSTOP and/or WS_ GROUP 
styles, which are fully described in Table 3.1. Styles can be combined using 
the bitwise OR operator. 


Comments 


The 2, y, width, and height fields can use addition and subtraction opera- 
tors (+ and —) for relative positioning. For example, “15 + 6” can be used 
for the = field. 


Default style for LTEXT is SS_ LEFT, WS_ GROUP. 


Example 


LTEXT "Enter Name:", 3, 10, 10, 40, 10 
3.10.2.2 RTEXT Statement 


Syntax 
RTEXT tezt, id, 2, y, width, height, [style] 


This statement defines a flush-right text control. It creates a simple rec- 
tangle that displays the given text flush-right in the rectangle. The text is 
formatted before it is displayed. Words that would extend past the end of 
a line are automatically wrapped to the beginning of the next line. 


The tezt field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 
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The 2d field takes a unique integer value that identifies the control. 


The zand y fields take integer values that specify the 2 and y coordinates 
of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 


The width and height fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field contains WS_TABSTOP and/or WS_GROUP 
styles, which are fully described in Table 3.1. Styles can be combined using 
the bitwise OR operator. 


Comments 
The 2, y, width, and hezght fields can use addition and subtraction opera- 
tors (+ and —) for relative positioning. For example, “15 + 6” can be used 


for the z field. 
Default style for RTEXT is SS_ RIGHT, WS_ GROUP. 


Example 


RTEXT "Number of Messages", 4, 30, 50, 100, 10 
3.10.2.3 CTEXT Statement 


Syntax 
CTEXT teat, id, x, y, width, height, [style] 


This statement defines a centered text control. It creates a simple rectan- 
gle that displays the given text centered in the rectangle. The text is for- 
matted before it is displayed. Words that would extend past the end of a 
line are automatically wrapped to the beginning of the next line. 


The éezt field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 
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The dd field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the z and y coordinates 
of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 


The width and height fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field contains WS_TABSTOP and/or WS_ GROUP 
styles, which are fully described in Table 3.1. Styles can be combined using 
the bitwise OR operator. 7 


Comments 
The 2, y, width, and height fields can use addition and subtraction opera- 


tors (+ and —) for relative positioning. For example, “15 + 6” can be used 
for the z field. 


Default style for CTEXT is SS_ CENTER, WS. GROUP. 


Example 


CTEXT "Title", 3, 10, 50, 40, 10 
3.10.2.4 CHECKBOX Statement 


Syntax 
CHECKBOX teat, id, x, y, width, height, [style] 


This statement defines a check-box control belonging to the BUTTON 
class. It creates a small rectangle (check box) that is highlighted when 
clicked. The given text is displayed just to the right of the check box. The 
control highlights the rectangle when the user clicks the mouse in it, and 
removes the highlight on the next click. 


The tezt field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 
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The zd field takes a unique integer value that identifies the control. 


The z and y fields take integer values that specify the z and y coordinates 
of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 


The width and height fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field contains WS_TABSTOP and/or WS_ GROUP 
styles, which are fully described in Table 3.1, and/or BUTTON-class 
styles, which are fully described in Table 3.3. Styles can be combined using 
the bitwise OR operator. 


Comments 
The 2, y, width, and height fields can use addition and subtraction opera- 
tors (+ and —) for relative positioning. For example, “15 + 6” can be used 


for the z field. 
Default style for CHECKBOX is BS. CHECKBOX, WS_ TABSTOP. 


Example 


CHECKBOX “Arabic”, 3; 10; 10; 40,10 
3.10.2.5 PUSHBUTTON Statement 


Syntax 
PUSHBUTTON text, id, 2, y, width, height, [style] 


This statement defines a rectangle containing the given tezt. The control 
sends a message to its parent whenever the user clicks the mouse inside the 
rectangle. 


The teat field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 
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The id field takes a unique integer value that identifies the control. 


The zand y fields take integer values that specifies the z and y coordinates 
of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 


The width and height fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field contains WS. TABSTOP, WS_ DISABLED, and/or 
WS_ GROUP styles, which are fully described in Table 3.1, and/or 
BUTTON-class styles, which are fully described in Table 3.3. Styles can be 
combined using the bitwise OR operator. 


Comments 
The 2, y, width, and height fields can use addition and subtraction opera- 
tors (+ and ~) for relative positioning. For example, “15 + 6” can be used 


for the z field. 

Default style for PUSHBUTTON is BS_ PUSHBUTTON, 
WS_ TABSTOP. 

Example 


PUSHBUTTON "ON", 7, 10, 10, 20, 10 
3.10.2.6 LISTBOX Statement 


Syntax 

LISTBOX id, x, y, width, height, [style] 

This statement defines a list box belonging to the LISTBOX class. It 
creates a rectangle that contains a list of strings (such as filenames) from 
which the user can make selections. 

The id field takes a unique integer value that identifies the control. 

The wand y fields take integer values that specify the rand y coordinates 


of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 7 
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The width and hezght fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field contains WS_BORDER and/or WS_ VSCROLL 
styles, which are fully described in Table 3.1, and/or LISTBOX-class 
styles, which are fully described in Table 3.3. Styles can be combined using 
the bitwise OR operator. 


Comments 


The a, y, width, and height fields can use addition and subtraction opera- 
tors (+ and —) for relative positioning. For example, “15 + 6” can be used 
for the z field. 


Default style for LISTBOX is LBS. NOTIFY, LBS_SORT, 
Ws_ VSCROLL, WS_ BORDER. 


For information on the recommended keys for use in list-box controls, see 
the Microsoft Windows Application Style Guide. 


Example 


LISTBOX 666, 10, 10, 50, 54 
3.10.2.7 GROUPBOX Statement 


Syntax 
GROUPBOX teat, id, 2, y, width, height, [style] 


This statement defines a group box belonging to the BUTTON class. It 
creates a rectangle that groups other controls together. The controls are 
grouped by drawing a border around them and displaying the given text in 
the upper-left corner. 


The teat field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. Selecting the mnemonic moves the input focus 
to the next control, in the order set in the resource file. To use the amper- 
sand as a character in a string, insert two ampersands (&&). 
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The zd field takes a unique integer value that identifies the control. 


The zand y fields take integer values that specify the x and y coordinates 
of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 


The width and height fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field contains WS_TABSTOP or WS_ DISABLED 
styles, which are fully described in Table 3.1, and/or BUTTON-class 


styles, which are fully described in Table 3.3. Styles can be combined using 


the bitwise OR operator. 


Comments 


The 2, y, width, and height fields can use addition and subtraction opera- 
tors (+ and —) for relative positioning. For example, “15 + 6” can be used 
for the 2 field. 


Default style for GROUPBOX is BS_ GROUPBOX, WS_ TABSTOP. 


Example 


GROUPBOX "Output", 42, 10, 10, 30, 50 
3.10.2.8 DEFPUSHBUTTON Statement 


Syntax 
DEFPUSHBUTTON text, id, 2, y, width, height, [style] 


This statement defines a default pushbutton control that belongs to the 
BUTTON class. It creates a small rectangle with a bold outline that 
represents the default response for the user. The text is displayed inside 
the button. The control highlights the button in the usual way when the 
user clicks the mouse in it and sends a message to its parent window. 


The tezt field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 
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The zd field takes a unique integer value that identifies the control. 


The z and y fields take integer values that specify the z and y coordinates 
of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 


The width and height fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field contains WS_TABSTOP, WS_ GROUP and/or 
WS... DISABLED styles, which are fully described in Table 3.1, and/or 
BUTTON-class styles, which are fully described in Table 3.3. Styles can be 
combined using the bitwise OR operator. 


Comments 


The 2, y, width, and height fields can use addition and subtraction opera- 
tors (+ and —) for relative positioning. For example, “15 + 6” can be used 
for the z field. 


Default style for DEFPUSHBUTTON is BS_ DEFPUSHBUTTON, 
WS_ TABSTOP. 


Example 


DEFPUSHBUTTON "ON", 7, 10, 10, 20, 10 
3.10.2.9 RADIOBUTTON Statement 


Syntax 
RADIOBUTTON test, id, x, y, width, height, [style] 


This statement defines a radiobutton control belonging to the BUTTON 
class. It creates a small rectangle that has the given text displayed just to 
its right. The control highlights the button when the user clicks the mouse 
in it and sends a message to its parent window. The control removes the 
highlight and sends a message on the next click. 


The tezt field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. To add a 
mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. To use the ampersand as a character in a 
string, insert two ampersands (&&). 
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The id field takes a unique integer value that identifies the control. 


The xzand y fields take integer values that specify the and y coordinates 
of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 


The width and height fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field contains WS. TABSTOP, WS_ GROUP and/or 
WS. DISABLED styles, which are fully described in Table 3.1, and/or 
BUTTON-class styles, which are fully described in Table 3.3. Styles can be 
combined using the bitwise OR operator. 


Comments 

The 2, y, width, and hezght fields can use addition and subtraction opera- 
tors (+ and —) for relative positioning. For example, “15 + 6” can be used 
for the z field. 


Default style for RADIOBUTTON is BS_ RADIOBUTTON, 
Ws. TABSTOP. 


Example 


RADIOBUTTON "AM 101", 10, 10, 10, 40, 10 
3.10.2.10 EDITTEXT Statement 


Syntax 
EDITTEXT id, 2, y, width, height, [style] 


This statement defines an EDIT control belonging to the EDIT class. It 
creates a rectangle in which the user can enter and edit text. The control 
displays a cursor when the user clicks the mouse in it. The user can then 
use the keyboard to enter text or edit the existing text. Editing keys 
include the BACKSPACE and DELETE keys. The user can also use the mouse 
to select the character or characters to be deleted, or to select the place to 
insert new characters. 


The zd field takes a unique integer value that identifies the control. 
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The zand y fields take integer values that specify the z and y coordinates 
of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 


The width and hezght fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field contains WS. TABSTOP, WS_ GROUP, 
WS. VSCROLL, WS_HSCROLL, and/or WS_ DISABLED styles, which 
are fully described in Table 3.1, and/or EDIT-class styles, which are fully 


described in Table 3.3. Styles can be combined using the bitwise OR 
operator. EDIT-class styles must not conflict. 


Comments 
The 2, y, width, and hezght fields can use addition and subtraction opera- 
tors (+ and —) for relative positioning. For example, “15 + 6” can be used 


for the z field. 


Default style for EDITTEXT is WS. TABSTOP, ES_ LEFT, 
WS. BORDER. 


Keyboard use is predefined for edit controls. Predefined keys are listed in 
the Microsoft Windows Application Style Guide. 
Example 


EDITTEXT 3, 10, 10, 100, 10 
3.10.2.11 ICON Statement 


Syntax 

ICON teat, id, 2, y, width, height, [style] 

This statement defines an icon control belonging to the STATIC class. It 
creates an icon displayed in the dialog box. The given text is the name of 


an icon (not a filename) defined elsewhere in the resource file. 


For the ICON statement, the width and height fields are ignored; the icon 
automatically sizes itself. 
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The id field takes a unique integer value that identifies the control. 


The zand y fields take integer values that specify the z and y coordinates 
of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 


The width and height fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


The optional style field allows only the SS_ICON style. 


Comments 

The z, y, width, and height fields can use addition and subtraction opera- 
tors (+ and —) for relative positioning. For example, “15 + 6” can be used 
for the z field. 


Default style for ICON is SS_ ICON. 
3.10.2.12 CONTROL Statement 


Syntax 
CONTROL teat, id, class, style, 2, y, width, height 
This statement defines a user-defined control window. 


The tezt field takes an ASCII string that specifies the text to be displayed. 
The string must be enclosed in double quotation marks. 


The id field takes a unique integer value that identifies the control. 


The class field takes a predefined name, character string, or integer that 
defines the class. It can be any one of the control classes; for a list of the 
control classes, see Table 3.2. If it is a predefined name supplied by the 
application, it must be an ASCII string enclosed in double quotation 
marks. 


The style field takes a predefined name or integer value that specifies the 
style of the given control. The exact meaning of style depends on the class 
value. Tables 3.2 and 3.3 list the control classes and corresponding styles. 


The zand y fields take integer values that specify the z and y coordinates 


of the upper-left corner of the control. The coordinates are relative to the 
origin of the dialog box. 
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The width and height fields take integer values that specify the width and 
height of the control. The width units are 1/4 of the width of a character; 
the height units are 1/8 of the height of a character. 


Comments 


The 2, y, width, and hezght fields can use addition and subtraction opera- 
tors (+ and —) for relative positioning. For example, “15 + 6” can be used 
for the z field. 


Table 3.2 describes the five control classes: 


Table 3.2 


Control Classes 
Class Description 


BUTTON — A button control is a small rectangular child window that 
represents a “button” that the user can turn on or off by 
clicking it with the mouse. Button controls can be used alone or 
in groups, and can either be labeled or appear without text. 
Button controls typically change appearance when the user 
clicks them. 


EDIT An edit control is a rectangular child window in which the user 
can enter text from the keyboard. The user selects the control, 
and gives it the input focus, by clicking the mouse inside it or 
pressing the TAB key. The user can enter text when the control 
displays a flashing caret. The mouse can be used to move the 
cursor and select characters to be replaced, or to position the 
cursor for inserting characters. The BACKSPACE key can be used 
to delete characters. 


Edit controls use the fixed-pitch font and display ANSI 
characters. They expand tab characters into as many space 
characters as are required to move the cursor to the next tab 
stop. Tab stops are assumed to be at every eighth character 
position. 


STATIC Static controls are simple text fields, boxes, and rectangles that 
can be used to label, box, or separate other controls. Static 
controls take no input and provide no output. 


LISTBOX __List-box controls consist of a list of character strings. The 
control 1s used whenever an application needs to present a list 
of names, such as filenames, that the user can view and select. 
The user can select a string by pointing to the string with the 
mouse and clicking a mouse button. When a string is selected, 
it is highlighted, and a notification message is passed to the 
parent window. A scroll bar can be used with a list-box control 
to scroll lists that are too long or too wide for the control 
window. 
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Table 3.2 (continued) 


Class Description 


SCROLLBAR  Ascroll-bar control is a rectangle that contains a scroll thumb 
and has direction arrows at both ends. The scroll bar sends a 
notification message to its parent whenever the user clicks the 
mouse in the control. The parent is responsible for updating the 
thumb position, if necessary. Scroll-bar controls have the same 
appearance and function as the scroll bars used in ordinary 
windows. Unlike scroll bars, scroll-bar controls can be 
positioned anywhere in a window and used whenever needed to 
provide scrolling input for a window. 


The scroll-bar class also includes Size-box controls. A Size-box 
control is a small rectangle that the user can expand to change 
the size of the window. 


Table 3.3 describes the control styles for each of the control classes: 


Table 3.3 
Control Styles 


Style Description 
BUTTON Class 
BS_ PUSHBUTTON A small elliptical button containing the given text. 


The control sends a message to its parent whenever 
the user clicks the mouse inside the rectangle. 


BS_DEFPUSHBUTTON = Asmall elliptical button with a bold border. This 
button represents the default user response. Any 
text is displayed within the button. Windows sends 
a message to the parent window when the user clicks 
the mouse in this button. 


BS_. CHECKBOX A small rectangular button that may be checked; its 
border becomes bold when the user clicks the mouse 
in it. Any text appears to the right of the button. 


BS_ AUTOCHECKBOX Identical to BS_ CHECKBOX except that the 
button automatically toggles its state whenever the 
user clicks it. 


Table 3.3 (continued) 
Style 


BS_ RADIOBUTTON 


BS_ AUTORADIOBUTTON 


BS_ LEFTTEXT 


BS_ 3STATE 


BS. AUTO8STATE 
BS_. GROUPBOX 


BS_ USERBUTTON 


EDIT Class 


ES_ LEFT 
Es_ CENTER 
ES. RIGHT 
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Description 


A small circular button whose border becomes 
bold when the user clicks the mouse in it. In 
addition, to make the border bold, Windows 
sends a message to the button’s parent notifying 
it that a click occurred. On the next click, 
Windows makes the border normal again and 
sends another message. 


Identical to BS. RADIOBUTTON except that the 
button is checked, the application is notified with 
BN_ CLICKED, and all other radio buttons in the 
group are unchecked. 


Causes text to appear on the left side of the radio 
button or check-box button. Use this style with 
BS_ CHECKBOX, BS_. 3STATE, or 

BS_ RADIOBUTTON styles. 


Identical to BS_ CHECKBOX except that a 
button can be grayed as well as checked or 
unchecked. The grayed state is typically used to 
show that a check box has been disabled. 


Identical to BS_ 3STATE except that the button 
automatically toggles its state when the user 
clicks it. 

A rectangle into which other buttons are grouped. 
Any text is displayed in the rectangle’s upper-left 
corner. 


A user-defined button. The parent is notified 
when the button is clicked. Notification includes 


- arequest to paint, invert, and disable the button. 


Flush-left text. 
Centered text. 
Flush-right text. 
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Table 3.3 (continued) 


Style 


ES_ MULTILINE 


EkS_ AUTOVSCROLL 


ES... AUTOHSCROLL 


ES — NOHIDESEL 
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Description 


Multiple-line edit control. (The default is single-line.) If 
the ES.. AUTOVSCROLL style is specified, the edit 
control shows as many lines as possible and scrolls 
vertically when the user presses the ENTER key. (This is 
actually the carriage-return character, which the edit 
control expands to a carriage-return/line-feed 
combination. A line feed is not treated the same as a 
carriage return.) If ES_AUTOVSCROLL is not given, 
the edit control shows as many lines as possible and 
beeps if the user presses ENTER when no more lines can 
be displayed. 


If the ES_ AUTOHSCROLL style is specified, the 
multiple-line edit control automatically scrolls 
horizontally when the caret goes past the right edge of 
the control. To start a new line, the user must press 
the ENTER key. If ES_ AUTOHSCROLL is not given, 
the control automatically wraps words to the beginning 
of the next line when necessary; a new line is also 
started if the user presses the ENTER. The position of 
the wordwrap is determined by the window size. If the 
window size changes, the wordwrap position changes, 
and the text is redisplayed. 


Multiple-line edit controls can have scroll bars. An edit 
control with scroll bars processes its own scroll-bar 
messages. Edit controls without scroll bars scroll as 
described above, and process any scroll messages sent 
by the parent window. 


Text is automatically scrolled up one page when the 
user presses the ENTER key on the last line. 


Text is automatically scrolled to the right by 10 
characters when the user types a character at the end 
of the line. When the user presses the ENTER key, the 
control scrolls all text back to position 0. 


Normally, an edit control hides the selection when the 
control loses the input focus, and inverts the selection 
when the control receives the input focus. Specifying 
ES_.NOHIDESEL overrides this default action. 


Table 3.3 (continued) 


Style 
STATIC Class 


ss_ LEFT 


so_ CENTER 


9S_ RIGHT 


95_ ICON 


SS_ BLACKRECT 
SS. GRAYRECT 
SS_ WHITERECT 
SS_ BLACKFRAME 
SS_ GRAYFRAME 
9S. WHITEFRAME 
SS_ USERITEM 


LISTBOX Class 
LBS_ NOTIFY 


LBS_ MULTIPLESEL 
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Description 


A simple rectangle displaying the given text flush left 
in the rectangle. The text is formatted before it is 
displayed. Words that would extend past the end of a 
line are automatically wrapped to the beginning of the 
next flush-left line. 


A simple rectangle displaying the given text centered in 
the rectangle. The text is formatted before it is 
displayed. Words that would extend past the end of a 
line are automatically wrapped to the beginning of the 
next centered line. 


A simple rectangle displaying the given text flush right 
in the rectangle. The text is formatted before it is 
displayed. Words that would extend past the end of a 
line are automatically wrapped to the beginning of the 
next flush-right line. 


An icon displayed in the dialog box. The given text is 
the name of an icon Ae a filename) defined elsewhere 
in the resource file. For the ICON statement, the width 
and height parameters in Create Window are ignored; 
the icon automatically sizes itself. 


Black-filled rectangle. 
Gray-filled rectangle. 
White-filled rectangle. 
Box with black frame. 
Box with gray frame. 
Box with white frame. 
User-defined item. 


The parent receives an input message whenever the 
user clicks or double-clicks a string. 


The string selection is toggled each time the user clicks 
or double-clicks the string. Any number of strings can 
be selected. 
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Table 3.3 (continued) 


Style Description 
LBS_ SORT The strings in the list box are sorted alphabetically. 
LBS_ NOREDRAW The list-box display is not updated when changes are ra 


made. This style can be changed at any time by 
sending a WM_SETREDRAW message. 


SCROLLBAR Class 
SBS_ VERT Vertical scroll bar. If neither SBS. RIGHTALIGN nor 


SBS_ LEFTALIGN is specified, the scroll bar has the 
height, width, and position given in the 
CreateWindow function. 


SBS. RIGHTALIGN Used with SBS. VERT. The right edge of the scroll bar 
is aligned with the right edge of the rectangle specified 
by the a, y, width, and height values given in the 
Create Window function. The scroll bar has the 
default width for system scroll bars. 


SBS_ LEF'TALIGN Used with SBS_ VERT. The left edge of the scroll bar 
is aligned with the left edge of the rectangle specified 
by the a, y, width, and hezght values given in the 
Create Window function. The scroll bar has the 
default width for system scroll bars. 


SBS_ HORZ Horizontal scroll bar. If neither SBS. BOTTOMALIGN 
nor SBS. TOPALIGN is specified, the scroll bar has 
the height, width, and position given in the 
Create Window function. 


SBS_ TOPALIGN Used with SBS_ HORZ. The top edge of the scroll bar 
is aligned with the top edge of the rectangle specified 
by the z, y, width, and height values given in the 
CreateWindow function. The scroll bar has the 
default height for system scroll bars. 


SBS. BOTTOMALIGN — Used with SBS_ HORZ. The bottom edge of the scroll 
bar is aligned with the bottom edge of the rectangle 
specified by the 2, y, width, and height values given in 
the CreateWindow function. The scroll bar has the 
default height for system scroll bars. 
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Table 3.3 (continued) 


Style Description 
SBS_ SIZEBOX Size box. If neither SBS_ SIZEBOX- 
BOTTOMRIGHTALIGN nor 


SBS_. SIZEBOXTOPLEFTALIGN is 
specified, the Size box has the height, 
width, and position given in the 
Create Window function. 

SBS_ SIZEBOXTOPLEFTALIGN Used with SBS_ SIZEBOX. The top- 
left corner of the Size box is aligned 
with the top-left corner of the 
rectangle specified by the 2, y, width, 
and hezght values given in the 
Create Window function. The Size 
box has the default size for system 
Size boxes. 

SBS_ SIZEBOXBOTTOMRIGHTALIGN — Used with SBS_.SIZEBOX. The 
bottom-right corner of the Size box is 
aligned with the bottom-right corner 
of the rectangle specified by the g, y, 
width, and height values given in the 
Create Window function. The Size 
box has the default size for system 
Size boxes. 


3.11 Directives 


The resource directives are special statements that define actions to be 
performed on the script file before it is compiled. The directives can assign 
values to names, include the contents of files, and control compilation of 
the script file. 


The resource directives are identical to the directives used in the C pro- 
gramming language. They are fully defined in the Microsoft C Reference 
Manual. 


3.11.1 #include Statement 


Syntax 
# include filename 


This directive copies the contents of the file specified by filename into your 
resource script before re processes the script. 
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The filename field takes an ASCII string, enclosed in double quotation 
marks, that specifies the DOS filename of the file to be included. A full 
pathname must be given if the file is not in the current directory or in the 
directory specified by the INCLUDE environment variable. 


The filename field is handled as a C string, and two backslashes must 
be given wherever one is expected in the pathname (for example, 

“root \sub”). A single forward slash (/) can be used instead of double 
backslashes (for example, “root/sub” ). 


Example 


t 


tinclude “windows.h" 


PenSelect MENU 
BEGIN 

Menuitem “&black pen", BLACK_PEN 
END | 


3.11.2 #define Statement 


Syntax 
# define name value 


This directive assigns the given value to name. All subsequent occurrences 
of name are replaced by value. 


The value field takes any integer value, character string, or line of text. 


Examples 
#define nonzero 1 
#define USERCLASS "MyControlClass" 


3.11.3 #undef Statement 


Syntax 
# undef name 


This directive removes the current definition of name. All subsequent 
occurrences of name are processed without replacement. 
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Examples 
#undef nonzero 
Hundef USERCLASS 


3.11.4 #ifdef Statement 


Syntax 
# ifdef name 


This directive carries out conditional compilation of the resource file by 
checking the specified name. If name has been defined using a # define 
directive, # ifdef directs the resource compiler to continue with the state- 
ment immediately after #ifdef. If name has not been defined, # ifdef 
directs the compiler to skip all statements up to the next #endif direc- 
tive. 


Example 


#ifdef Debug 
errbox BITMAP errbox.bmp 
#endif 


3.11.5 ifndef Statement 


Syntax 
# ifndef name 


This directive carries out conditional compilation of the resource file by 
checking the specified name. If name has not been defined or if its 
definition has been removed using the # undef directive, #ifndef directs 
the resource compiler to continue processing statements up to the next 

# endif, #else, or #elif directive, then skip to the statement after 

# endif. If name is defined, #ifndef directs the compiler to skip to the 
next #endif, #else, or #elif directive. 


Example 


#ifndef Optimize 
errbox BITMAP errbox.bmp 
#endif 
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3.11.6 #if Statement 


Syntax 
# if constant-expression 


This directive carries out conditional compilation of the resource file by 
checking the specified constant-ezpression. If constant-ezpression 1s 
nonzero, #if directs the resource compiler to continue processing state- 
ments up to the next #endif, #else, or #elif directive, then skip to the 
statement after #endif. If constant-expression is zero, # if directs the 
compiler to skip to the next #endif, #else, or #elif directive. 


The constant-ezpression field specifies a defined name, an integer constant, 
or an expression consisting of names, integers, and arithmetic and rela- 
tional operators. 


Example 


#if Version<3 
errbox BITMAP errbox.bmp 
teondif 


3.11.7 elif Statement 


# elif constant-expression 


This directive marks an optional clause of a conditional compilation block 
defined by an # ifdef, # ifndef, or #if directive. The # elif directive car- 
ries out conditiona] compilation of the resource file by checking the 
specified constant-expression. If constant-expression is nonzero, 7 elif 
directs the resource compiler to continue processing statements up to the 
next #endif, #else, or #elif directive, then skip to the statement after 
#tendif. If constant-ezpression is zero, 7 elif directs the compiler to skip 
to the next #endif, #else, or #elif directive. Any number of #elif 
directives can be used in a conditional block. 


The constant-expression field specifies a defined name, an integer constant, 


or an expression consisting of names, integers, and arithmetic and rela- 
tional operators. 
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Example 


#if Version<3 

errbox BITMAP errbox.bmp 
#elif Version<7 

errbox BITMAP userbox.bmp 
#endif 


3.11.8 #else Statement 


Syntax 
# else 
This directive marks an optional clause of a conditional compilation block 


defined by an # ifdef, # ifndef, or #if directive. The #else directive 
must be the last directive before # endif. 


Example 


#ifdef Debug 

errbox BITMAP errbox.bmp 
#else 

errbox BITMAP userbox.bmp 
#endif 


3.11.9 endif Statement 


Syntax 
# endif 


This directive marks the end of a conditional compilation block defined by 
an # ifdef directive. One #endif is required for each # ifdef directive. 
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4.1 Introduction 


You create executable Microsoft Windows applications and libraries by 
linking your compiled source files using the link4 program. The link4 pro- 
gram takes your compiled sources, a list of Windows and other libraries, 
and a module-definition file (a text file containing information about your 
application or library) and creates a file that you can load and run with 
Windows. 


This chapter describes how to use link4, how to create module-definition 
files, and how to name the libraries to be used with your application 
library. 


4.2 Creating Module-Definition Files 


A module-definition file is an ordinary text file that defines the contents 
and system requirements of a Windows application or library. The file con- 
tains one or more module statements, each defining a specific attribute 

of the application or library, such as its module name, the number and 
type of program segments, and the number and names of exported and 
imported functions. Every application and library must have a module- 
definition file. 


You must create the file before linking the application. The file contains 
one or more definition statements. Each statement defines some aspect of 
the application or library, such as its module name and segment types. 
You can choose any filename for the file, but you must use the filename 
extension .def. 


4.2.1 Module Definitions for Applications 


A module-definition file for an application must contain a NAME 
statement that defines the application’s module name. This name is used 
by Windows to identify the application. Although this is the only required 
statement in the module-definition file, most files contain additional state- 
ments, such as the DATA and CODE statements, that define other 
aspects of the application. 


The following example shows a typical module-definition file for an 
application: 


:; Sample Module Definition File 
NAME Sample | 
DESCRIPTION ‘Sample Window Application' 
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DATA MULTIPLE MOVEABLE 
CODE MOVEABLE 


HEAPSIZE 4096 
STACKSIZE 4096 


EXPORTS 
SampleWndProc @1 


In this example, the module name is “Sample.” This module has multiple 
data segments (one for each instance). The data and code segments are 
moveable. The heap and stack sizes are 4096 bytes. The window function 
named “SampleWndProc” is the procedure exported so that Windows can 
call it. The application imports no functions. 


It is recommended that applications have at least 4096 bytes of stack 
space. Heap space is required if the application uses its local heap. The 
application’s data segment must be multiple, since any application can 
be invoked more than once. Moveable code and data segments are recom- 
mended, since they allow Windows to take best advantage of memory. 


The first line of the sample module-definition file is a comment. A com- 
ment can appear on a line by itself or on the same line as a definition, as 
long as it appears after the definition. A comment must be preceded by 
a semicolon (;). 7 


4.2.2 Module Definitions for Libraries 


A module-definition file for a library must contain a LIBRARY statement 
that defines the library’s module name. This name is used by Windows to 
identify the application. The file must also contain an EXPORT state- 
ment that lists the functions to be exported by the library. Functions in 
the library are not accessible if not listed. 


The following example shows a typical module-definition file for a library: 


; Example Module Definition File 
LIBRARY Example 
DESCRIPTION ‘Example Window Library' 


DATA SINGLE MOVEABLE 
CODE MOVEABLE 


HEAPSIZE 4096 


EXPORTS 
ExampleInit @1 
ExampleStart @2 
ExampleEnd @3 
ExampleLoad @4 
ExampleSave @5 
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In this example, the module name is “Example.” This module has single 
data segments (only one instance of a library is ever allowed). The data 
and code segments are moveable. The heap size is 4096 bytes. No STACK 
statement is given, which means that the library will use the stack of the 
calling application. The exported functions are listed by name and ordinal 
number. These are the names or numbers that you can put in the 
IMPORT statement of an application’s module-definition file to indicate 
that the application calls the library. 


4.3. Module-Definition Statements 


The module-definition file contains one or more of the following module 
statements: 


Statement Description 

NAME Module name 
LIBRARY Library name 
DESCRIPTION One-line description of the module 
DATA Data-segment attributes 
CODE Code-segment attributes 
HEAPSIZE Local-heap size in bytes 
STACKSIZE Local-stack size in bytes 
SEGMENTS Additional code segment 
EXPORTS Exported functions _ 
IMPORTS Imported functions 
STUB Old-style executable 


4.3.1 NAME Statement 

Syntax 

NAME modulename 

This statement defines the name of the application’s executable module. 
The name is used to identify the module when importing or exporting 


functions. 


The modulename field specifies one or more ASCII characters. 


75 


Microsoft Windows Programming Tools 


Comments 

The modulename field is optional. If the field is not given, the linker uses 
the filename part of the executable file (that is, the name with the exten- 
sion removed). 

If neither a NAME nor a LIBRARY statement is given in the definition 


file, the linker assumes that a NAME statement without a modulename 
field is desired. 


Example 


NAME Calendar 


4.3.2 LIBRARY Statement 

Syntax 

LIBRARY ([ibraryname 

This statement defines the name of a library module. Library modules are 
resource modules that contain code, data, and other resources but are not 
intended to be executed as an independent program. 

The libraryname field specifies one or more ASCII characters that define 
the name of the library module. 


Comments 


The start address of the module is determined by the object files. It is an 
internally defined function. 


The libraryname field is optional. If the field is not given, the linker uses 


the filename part of the executable file (that is, the name with the exten- 
sion ee) 


. 


Example 


LIBRARY User 
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4.3.3 DESCRIPTION Statement 
Syntax 
DESCRIPTION ’tez?’ 


This statement inserts text into the application’s module. It is useful for 
embedding source-control or copyright information. 


The tezt field specifies one or more ASCII characters. The string must be 
enclosed in single quotation marks. 
Example 


DESCRIPTION ‘Microsoft Windows Template Application' 


4.3.4 HEAPSIZE Statement 

Syntax 

HEAPSIZE bytes 

This statement defines the number of bytes needed by the application for 
its local heap. An application uses the local heap whenever it allocates 
local memory. 

The default heap size is zero. 

The byées field takes an integer value that specifies the heap size in bytes. 
It must not exceed 65,536 (the size of a single physical segment). 


Example 


HEAPSIZE 4096 


4.3.5 STACKSIZE Statement 

Syntax 

STACKSIZE bytes 

This statement defines the number of bytes needed by the application for 


its local stack. An application uses the local stack whenever it calls its own 
functions. A minimum stack size of 4096 bytes is recommended. 
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The default stack size is zero, if the application makes no function calls. 


Otherwise, it 1s 4096. 


The bytes field takes an integer value that specifies the stack size in bytes. 


Example 


STACKSIZE 4096 


4.3.6 CODE Statement 


‘Syntax 


CODE [segment-attributes] 


This statement defines the attributes of the standard code segment. 

The standard code segment is the application segment having the name 

_ TEXT and belonging to the class CODE. In C applications, the standard 
segment is created automatically if no specific segment name is given in 
the C-compiler command line. 


The segment-attributes field takes one or more optional keywords that 
specify the code-segment attributes. They can be any combination of the 


following: 
Keyword 


FIXED 
MOVEABLE 


DISCARDABLE 
PRELOAD 
LOADONCALL 
SHARED 
NONSHARED 
EXECUTEONLY 
EXECUTEREAD 
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Description 


Segment remains at a fixed memory location. 


Segment can be moved if necessary to compact 
memory. 


Segment can be discarded if no longer needed. 
Segment is loaded immediately. 

Segment is loaded when called. 

Segment can be shared. 

Segment cannot be shared. 

Segment can be executed only. 


Segment can be read as data as well as executed. 
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Comments 


If no CODE statement is given in the module-definition file, the default 
attributes for the segment are MOVEABLE, PRELOAD, "NON- 
SHARED, and EXECUTEREAD. 


If a CODE statement is given, the default attributes are FIXED, 
LOADONCALL, N ONSHARED, and EXECUTEREAD, unless 


these are explicitly overridden. 


If conflicting options are given in the same statement, link4 uses the over- 
riding option to determine the segment attributes. MOVEABLE over- 
rides FIXED; PRELOAD overrides LOADONCALL; SHARED over- 
rides NONSHARED; and EXECUTEONLY overrides 
EXECUTEREAD. 


SHARED, NONSHARED, EXECUTEONLY, and EXECUTE- 
READ are used for 80286 protected-mode programs only. 


PURE and IMPURE are alternate keywords that can be used in place of 
SHARED and NONSHARED, respectively. 


Example 


CODE MOVEABLE LOADONCALL 


4.3.7 DATA Statement 
Syntax 
DATA [segment-attributes] 


This statement defines the attributes of the standard data segment. The 
standard data segment is all application segments belonging to the group 
DGROUP and the class DATA. In C applications, the standard data seg- 


ment is created automatically. 


The segment-attributes field takes one or more optional keywords that 
specify the attributes of the data segment. They can be any combination 
of the following: 


Keyword Description 
NONE There is no data segment. | 
SINGLE A single segment is shared by all instances of the 


module (valid only for library modules). 
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MULTIPLE One segment exists for each instance. 

FIXED Segment remains at a fixed memory location. 

MOVEABLE Segment can be moved if necessary to compact 
memory. 

DISCARDABLE Segment can be discarded if no longer needed. 

PRELOAD Segment is loaded immediately. 

LOADONCALL Segment is loaded when accessed. 

SHARED Segment contains data that does not change 
during execution. 

NONSHARED Segment contains data that may change during 
execution. 

READONLY Segment contents can be read only. 

READWRITE Segment contents can be read and modified. 

Comments 


If no DATA segment is given in the module-definition file, the default 


attributes for the segment are MULTIPLE, MOVEABLE, PRELOAD, 
NONSHARED, and READWRITE. 


Ifa DATA statement is given, the default attributes are MULTIPLE, 
FIXED, LOADONCALL, NONSHARED, and READWRITE, 
unless these are explicitly overridden. 


If conflicting options are given in the same statement, link4 uses the over- 
riding option to determine the segment attributes. MULTIPLE overrides 
NONE and SINGLE; SINGLE overrides NONE; MOVEABLE over- 

rides FIXED; PRELOAD overrides LOADONCALL; SHARED over- 
rides NONSHARED; and READONLY overrides READWRITE. 


The SINGLE option implies SHARED, and vice versa; MULTIPLE 
implies NONSHARED, and vice versa. Link4 ignores SHARED if it is 
used with MULTIPLE and ignores NONSHARED if it is used with 
SINGLE. 


SHARED, NONSHARED, READONLY, and READWRITE are 
used for 80286 protected-mode programs only. 


PURE and IMPURE are alternate keywords that can be used in place of 
SHARED and NONSHARED, respectively. 
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DATA MOVEABLE SINGLE 


Windows Linker: Link4 


4.3.8 SEGMENTS Statement 


Syntax 


SEGMENTS segmentname [CLASS ’class-name’] [minalloc] |segment-attributes] 


This statement defines the segment attributes of additional code and data 


segments. 


The segmentname field specifies a character string that names the new seg- 
ment. It can be any name, including the standard segment names — TEXT 
and DATA that represent the standard code and data segments. 


The class-name field takes an optional keyword that specifies the class 
name of the given segment. If no class name is given, link4 assumes the 
class name CODE by default. 


The menalloc field takes an integer value that specifies the minimum allo- 
cation size for the segment. 


The segment-attributes field takes one or more optional keywords that 
specify the attributes of the given segment. They can be any combination 


of the following: 
Keyword 


FIXED 
MOVEABLE 


DISCARDABLE 
SHARED 
NONSHARED 
PRELOAD 
LOADONCALL 
EXECUTEONLY 
EXECUTEREAD 
READONLY 
READWRITE 


Description 


Segment remains at a fixed memory location. 


Segment can be moved if necessary to compact 
memory. 


Segment can be discarded if no longer needed. 
Segment can be shared. 

Segment cannot be shared. 

Segment is loaded immediately. 

Segment is loaded when accessed or called. 
Segment can be executed only. 

Segment can be read as data as well as executed. 
Segment contents can be read only. 


Segment contents can be read and modified. 
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Comments 


If no SEGMENTS statement is given in the module-definition file, the 
default attributes for nonstandard segments are MOVEABLE, PRE- 
LOAD, NONSHARED, and EXECUTEREAD. 


If a SEGMENTS statement is given but only a segment name and class 
are given, the default attributes are FIXED, LOADONCALL, NON- 
SHARED, and EXECUTEREAD or READWRITE, unless these are 


explicitly overridden. 


If conflicting options are given in the same statement, link4 uses the over- 
riding option to determine the segment attributes. MOVEABLE over- 
rides FIXED; PRELOAD overrides LOADONCALL; SHARED over- 
rides NONSHARED; EXECUTEONLY overrides EXECUTEREAD; 
and READONLY overrides READWRITE. 


SHARED, NONSHARED, EXECUTEONLY, and EXECUTE- 
READ are used for 80286 protected-mode programs only. 


PURE and IMPURE are alternate keywords that can be used in place of 
SHARED and NONSHARED, respectively. 


Example 


SEGMENTS 
_TEXT FIXED 
_INIT PRELOAD DISCARDABLE 
_RES CLASS '‘DATA' PRELOAD DISCARDABLE 


4.3.9 EXPORTS Statement 


Syntax 

EXPORTS exportname [ordinal-option] [res-option| [data-option] [parameter-option|] 
This statement defines the names and attributes of the functions to be 
exported to other applications. The EXPORTS keyword marks the 
beginning of the definitions. It can be followed by any number of export 
definitions, each on a separate line. 


The exportname field specifies one or more ASCII characters that defines 
the function name. It has the following form: 


<entryname> [==<internalname] 
where the entryname field specifies the name to be used by other applica- 


tions to access the exported function, and internalname is an optional field 
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that defines the actual name of the function if entryname is not the actual 
name. 


The optional ordinal-option field defines the function’s ordinal value. It has 
the following form: 


@ ordinal 


where ordinal takes an integer value that specifies the function’s ordinal 
value. The ordinal value defines the location of the function’s name in the 
application’s string table. 


The res-option field takes the optional keyword RESIDENTNAME, 


which specifies that the function’s name must be resident at all times. 
The data-option field takes the optional keyword NODATA, which 
specifies that the function is not bound to a specific data segment. When 
invoked, the function uses the current data segment. 


The parameter-option field takes an optional integer value that specifies 
the number of words the function expects to be passed as parameters. 


Example 


EXPORTS 
SsampleRead=read2bin @1 8 
StringIn=stril @2 4 
CharTest NODATA 


4.3.10 IMPORTS Statement 

Syntax 

IMPORTS [internal-option] modulename [entry-option] 

This statement defines the names and attributes of the functions to be 
imported from other applications. The IMPORTS keyword marks the 
beginning of the definitions. It can be followed by any number of import 


definitions, each on a separate line. 


The optional znternal-option field specifies the name that the application 
will use to call the function. It has the following form: 


anternal-name= 


where znternal-name is one or more ASCII characters. This name must be 
unique. 
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The modulename field specifies the name of the executable module that 
contains the function. 


The optional entry-option field specifies the function to be imported. It can 
be one of the following: 


.entryname 
.entryordinal 


where entryname is the actual name of the function, and entryordinal is 
the ordinal value of the function. 


Example 


IMPORTS 
Sample.SampleRead 
write2Zhex=Sample.SampleWrite 
Read.1 


4.3.11 STUB Statement 
Syntax 
STUB ‘filename’ 


This statement appends the old-style executable file given by filename to 
the beginning of the module. The executable stub should display a warn- 
ing message and terminate if the user attempts to execute the module 
without having loaded Windows. The default file winstub.exe can be used 
if no other actions are required. 


The filename field specifies the name of the old-style executable file that 
will be appended to the module. The name must have the DOS filename 
format. 


Comments 
If the file named by filename is not in the current directory, the linker 


searches for the file in the directories specified by the user’s PATH 
environment variable. 
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Example 


STUB 'winstub.exe' 


4.4 Linking an Application 


You can link the compiled application source files, the Windows library, 
and the module-definition files by using link4, the Windows linker. The 
link4 program combines the code and data of all application files with the 
appropriate code for any Windows functions called from within the appli- 
cation, and creates a new linked file that is in executable format. 


4.4.1 Link4 Command 
Syntax 
link4 [options] object-files, | exe-file] | map-file] ,[lib-files], def-file 


The options parameter specifies one or more keywords (described in Sec- 
tion 4.4.2) that direct link4 to carry out special operations. 


The object-files parameter specifies the filenames of compiled application 
source files. If your application has more than one compiled source file, you 
must name all of them when you link. This means that you can give more 
than one object-file if necessary. Multiple filenames must be separated by 
spaces or the plus sign (+). 


The ezxe-file parameter specifies the name you want the executable file to 
have. 


The map-file parameter specifies the name you want the map file to have. 


The l2b-files parameter specifies the names of Windows or standard- 
language libraries. 


The def-file parameter specifies the filename of the module-definition file. 
No application may have more than one def-file. 


Commas are required to separate parameters in the command line. 


Example 


link4 sample/A:16,sample.exe,sample.map/map/li,slibw,sample.def 
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The command line in this example links the application object file 
sample.ob7 with the standard Windows library slibw.lib. This command 
creates the file sample.exe, which has the module name, segments, and 
exported functions defined by the module-definition file sample.def. It 
also creates the mapping file sample.map, which is used for symbolic 
debugging. The command searches the library file slzbw.lib to resolve 
any external function calls made in the application files. It also searches 
any libraries in the object file’s default library list. 


Note 


The link4 program uses default filename extensions if you do not 
explicitly provide extensions. Thus, in the preceding example, the file- 
name sample is extended to sample.obj. Library names are extended 
with the ./éb extension. 


4.4.2 Link4 Options 
The following list describes the link4 options: 
Option Description 


/alignment:size This option directs link4 to align segment 
data in the executable file along the boun- 
daries specified by size. The stze parameter 
specifies a boundary size in bytes; for exam- 
ple, “alignment:16” indicates an alignment 
boundary of 16 bytes. The recommended 
alignment for Windows applications is 16 
bytes. The seze parameter must be a power 
of 2; therefore, 2, 4, 8, 16, and so on are 
appropriate values. The default is 512 bytes. 
Minimum abbreviation: /a. 


/help This option directs link4 to display a list of 
available options. Minimum abbreviation: 


/linenumbers This option directs link4 to copy line- 
number information from the object file to 
the map file. The option is typically used to a 
prepare the map file for use with a source- 
level debugger, such as symdeb. Minimum 
abbreviation: /li. 


86 


/map 


/nofarcalltrans 


/noignorecase 


/packcode|:number] 


/pause 


/segments:number 


/stack:size 


/warnfixup 
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This option directs link4 to copy informa- 
tion about each symbol in the application to 
the map file. The option is typically used to 
prepare a map file for use with a symbolic 
debugger, such as symdeb. 


This option prevents the translation of far 
calls within the current segment. Without 
this option, far calls are translated into the 
following assembler statements: 


NOP 
PUSH CS 
NEAR CALL 


Minimum abbreviation: /nof. 


This option directs link4 to preserve lower- 
case letters when matching symbols during 
linking. Minimum abbreviation: /noi. 


This option directs link4 to pack contiguous 
logical or memory-code segments into one 
physical or file segment. The number param- 
eter specifies the size limit of the segment in 
bytes. If no number is given, the default is 
65,536. Minimum abbreviation: /pac. 


This option directs link4 to pause before 
copying the executable file to disk. Minimum 
abbreviation: /pau. 


This option sets the maximum number of 
segments link4 will process. The default is 
128 segments. Minimum abbreviation: /se. 


This option directs link4 to set the stack 
size to size bytes. This option is typically 
used in place of the STACKSIZE state- 
ment in the module-definition file. Minimum 
abbreviation: /st. 


This option causes link4 to display an error 
message when an offset fixup (relative to a 

logical segment) that is outside the physical 
segment occurs. Minimum abbreviation: /w. 
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Note 


There is an additional option, /nodefaultlibrarysearch, which 
causes link4 to ignore default libraries. Some language compilers, such oe 
as the Microsoft C Compiler, add default-library information to the 
object file. To ensure that the necessary library information 1s added 
to your application’s object files, do not use this option. 


4.5 Creating Import Libraries 


You can create import libraries for Windows libraries by using the implib 
command. The command creates an import-library file that can be speci- 
fied in the link4 command line with other libraries. Import libraries are 
required for all Windows libraries that can be linked dynamically. When 
you create a Windows library, you must create an import library to be 
specified on the link4 command line of the applications that use that 
library. 


Syntax 
implib imp-lib-name mod-def-file 


The imp-lib-name parameter specifies the name you want the new import 
hbrary to have. 


The mod-def-file parameter specifies the name of the module-definition file 
for the Windows library. 

Example 

implib mylib.1lib mylib.def 


This command creates the import library named mylzb.4b from the 
module-definition file mylzb. def. 
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4.6 Examining Executable File Headers 


You can use the exehdr command to determine whether an executable 
file is a Windows application or a library. The command also lets you find 
out which functions are exported or imported by a module, determine the 
amount of space allocated for a module’s heap or stack, and determine 
the size and number of the segments a module contains. 

Syntax 


exehdr eze-filename 


The eze-filename parameter specifies the name of any file with a .eze 
extension. 


Example 
exehdr hello.exe 
This command displays the header for the executable file hello.ere. The 


format of this header is closely related to the statements contained in the 
application’s module-definition file. 
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5.1 Introduction 


The Microsoft Symbolic Debug Utility (symdeb) is a debugging program 
that helps you test executable files. You can display and execute program 
code, set breakpoints that stop the execution of your program, examine 
and change values in memory, and debug programs that use the floating- 
point emulation conventions used by Microsoft languages. 


The symdeb utility lets you refer to data and instructions by name rather 
than by address. The symdeb utility can access program locations 
through addresses, global symbols, or line-number references, making it 
easy to locate and debug specific sections of code. 


You can debug C and Pascal programs at the source-file level as well as at 
the machine level. You can display the source statements of a program, 
the disassembled machine code of the program, or a combination of source 
statements and disassembled machine code. 


The symdeb utility accepts source line numbers as arguments to com- 
mands for displaying and changing data, setting breakpoints, and tracing 
execution. 


This chapter explains how to use symdeb to debug Windows applications. 
In particular, it describes how to do the following: 

e Prepare symbol files for an application 

e Set up the debugging terminal 

e Start symdeb with Windows 

e Interpret symdeb’s allocation messages 

e Display the application’s code and view its source file 

e Set breakpoints and interpret backtraces 

e Work with multiple instances of the same application 


e Kall an application and quit symdeb 
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Note 


If you have both a standard and a debugging version of Windows, 

symdeb may retrieve the incorrect version of certain files for use in a 
debugging. To correct this problem, include in your DOS PATH vari- 
able the name of the development directory you created when install- 

ing the development kit. (If the directory with the standard version of 

Windows is in your PATH variable, be sure the development directory 

is listed first.) Then symdeb will automatically retrieve files from the 

debugging version of Windows. 


5.2 Preparing Symbol Files 


Windows applications are difficult to debug without symbolic information 
about Windows and the application. To take advantage of symdeb’s 
symbolic features, you must first prepare a symbol file that symdeb can 
use. 


The steps for setting up a symbol file depend on the method used to create 
the program. The following sections describe those steps for applications 
written in C, Pascal, or assembly language. 


5.2.1 Mapsym Program 


The mapsym program creates symbol files for symbolic debugging. The 
program converts the contents of an application’s symbol map oe) file 
into a form suitable for loading with symdeb, copying the result to a 
symbol (.sym) file. 


Syntax 

mapsym [{/}—-}l] [{/|—}n] mapfitename 

Parameter Description 

mapfilename Specifies the filename for a symbol map file that was ee 


created during linking. If you do not give a filename 
extension, .map is assumed. If you do not give a full 
pathname, the current directory and drive 1s 
assumed. The mapsym program creates a new 
symbol file having the same name as the map file 
but with the .sym extension. 
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/l Directs mapsym to display information about the 
conversion on the screen. The information includes 
the names of groups defined in the program, the 
program start address, the number of segments, and 
the number of symbols per segment. 


/n Directs mapsym to ignore line-number information 
in the map file. The resulting symbol file contains 
no line-number information. 


Example 
mapsym /l file.map 


In this example, mapsym uses the symbol information in file.map to 
create file.sym on the current drive and directory. Information about the 
conversion will be sent to the screen. 


Note 


The mapsym program always places the new symbol file in the 
current drive and directory. 


To create a map file for mapsym input, you must specify the /map 
option when linking. To add hine-number information to the map file, 
you specify the appropriate option when compiling, and specify the 
/linenumbers option when linking. 


The mapsym program can process up to 10,000 symbols for each seg- 
ment in the application. 


5.2.2 Symbols with C-Language Applications 


To prepare a symbol file for an application written in the C language, 
follow these steps: 


1. Compile your source file using the ~—Zd option to produce line 
numbers in the object file. Debugging is easier if you disable the 
compiler’s optimization. 


2. Link the object file to produce an executable version of the pro- 
gram. Specify a map filename in the linker’s command line and give 
the /map and /linenumbers options. Make sure the map file- 
name is the same as the application’s module name given in the 
module-definition file. 
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3. Use the mapsym program to produce a symbol file. 


Example 


cl -d -c -AS ~Gsw -Os -Zdp test.c 
link4 test,test,test/map/li,slibw, test 
mapsym test 


5.2.3. Symbols with Assembly-Language Applications 


To prepare symbol files for Windows applications written in assembly 
language, follow these steps: 


1. Make sure that all symbols you may want to use with symdeb are 
declared public. Segment and group names should not be declared 
public. They are automatically available for debugging. 


2. Assemble your source file. 


Link the object file to produce an executable version of the applica- 
tion. Specify a map filename in the linker’s command line and give 
the /map option. Make sure the map filename is the same as the 
application’s module name given in the module-definition file. 


4. Use the mapsym program to create a symbol file. 


Example 


masm test; 
link4 test,test,test/map,slibw slibc libh,test 
mapsym test 


5.3 Setting Up the Debugging Terminal 


While it is running, Windows takes complete control of the system con- 
sole, making debugging through the console impossible. To debug Win- 
dows applications, you can either set up a remote terminal, connected 
through the computer’s serial port, or set up a secondary monochrome 
display adapter and monitor. 
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5.3.1 Setting Up a Remote Terminal 
To set up a remote terminal for debugging, follow these steps: 


1. Select a serial port on your computer and connect a terminal to it. 


2. Use the DOS mode command to set the baud rate and line proto- 
col of the serial line to correct values for use with the terminal. 
Line protocol includes the number of stop bits, type of parity 
checking, and number of transmission bits used by the terminal. 


3. When you start symdeb, redirect symdeb’s input and output to 
the remote terminal using the = command to specify a communi- 
cations port. For example, the command “=com2” redirects all 
subsequent symdeb command input and output to com2. 


Note 


Debugging through a remote terminal disables the normal function of 
the CONTROL-+S keys. These keys cannot be used while debugging Win- 
dows applications. 


5.3.2 Setting Up a Secondary Monitor 
To set up a secondary monitor for debugging, follow these steps: 


1. Install a secondary monochrome display adapter in a free slot of 
your computer and connect the monochrome monitor to it. 


2. Set the secondary display adapter switches to the appropriate set- 
tings. Follow the display adapter and computer manufacturer’s 
recommendations. 


3. When you start symdeb, use the /m option to redirect symdeb 
output to the secondary monitor. 


Note 


When the /m option is given, symdeb redirects output to the secon- 
dary monitor, but continues to use the system keyboard for input until 
the application being debugged is started. While the application is 
running, symdeb yields complete control of the keyboard to the appli- 
cation. As soon as the application reaches a breakpoint or terminates, 
symdeb reclaims the keyboard and permits user input again. 
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5.4 Starting Symdeb with Windows 


To start symdeb with Windows, enter the following symdeb command 
line at the DOS command prompt: 


a 


symdeb [options] |symbolfiles] win.com [arguments] 


The options parameter specifies one or more symdeb options. The 
symbolfiles parameter specifies the names of symbol files. The arguments 
parameter specifies arguments that you want to pass to win.com. 


Once started, symdeb displays a startup message followed by the 
symdeb command prompt (-). When you see the prompt you can enter 
symdeb commands. The symdeb commands are described in Section 5.9. 


Section 5.4.1 describes the elements of the symdeb command line. 


5.4.1 Symdeb Options 


You can specify one or more symdeb options in the command line. The 
symdeb options control the operation of symdeb while debugging Win- 
dows applications. Options must appear before win.com on the command 
line so that symdeb will not interpret them as program arguments. 


The symdeb utility has the following command-line options: 
Option Meaning 


/m Redirects symdeb output to a secondary monochrome 
monitor and permits debugging of Windows applications 
without redirecting input and output to a remote terminal. 
The symdeb utility assumes that the necessary display 
adapter and monitor are installed. 


/x Disables the “more” feature. Unless this option is specified, 
symdeb automatically stops lengthy output and does not 
continue the display until the user presses a key. ‘The 
symdeb utility stops the output after displaying enough 
lines to fill the screen, then prompts the user to continue by 
displaying the message “{more]”. If this option is specified, 
symdeb continues to display output until the command is 
completely executed. 


/wnumber Sets the memory-allocation reporting level. The reporting 
level defines what kind of memory allocation and movement 
messages symdeb is to display when Windows loads and 
moves program segments. The number parameter specifies 
the reporting level and can be 0, 1, 2, or 3. Level 0 specifies 
no reporting. Level 1, the default level if the /w option is 
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not given, generates allocation messages only. Level 2 gen- 
erates movement messages only. Level 3 generates both 
allocation and movement messages. See Section 5.7 for 
more information about allocation messages. 


Directs symdeb to load macro definitions from the file 
specified by filename. Macro definitions define the meaning 
of symdeb’s ten macro commands. The given file must con- 
tain one or more macro definitions in the following form: 


mnumber=command-string 


The number parameter specifies the macro, and command- 
string specifies one or more symdeb commands separated 
by semicolons (;). 


Permits use of non-maskable interrupts on non-[IBM 
computers. To use non-maskable interrupts, you must have 
a system that is equipped with the proper hardware, such 
as the following products: 


e IBM Professional Debugging Facility 
e Software Probe (Atron Corporation) 
The symdeb utility requires only the hardware provided 


with these products; no additional software is needed. If 
you are using one of these products with a non-IBM system, 


_ you must use the /n option to take advantage of the break 


capability. Using a non-maskable-interrupt break system is 
more reliable than using the interactive break key because 
you can always stop program execution regardless of the 
state of interrupts and other conditions. 


Directs symdeb to use features available on IBM- 
compatible computers. The option is not necessary if you 
have an IBM PC, because symdeb automatically checks 
the hardware on startup. If symdeb does not find that the 
hardware is an IBM PC, it assumes that the hardware is a 
generic MS-DOS machine. Without the option, symdeb 
cannot take advantage of special hardware features such as 
the 8259 Interrupt Controller, the [BM-style video display, 
and other capabilities of the IBM basic input and output 
system (BIOS). 


Prevents association of the named symbol file with the exe- 
cutable file that has the same name. This option is rarely 
used and is not recommended for debugging Windows 
applications. 


Directs symdeb to execute commands in the commands list 
immediately after starting. Commands in the list must be 
separated with semicolons and the entire list must be 
enclosed in double quotation marks. The / is required. 
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Note 


The option designator can be either a slash (/) or a hyphen UC) and the 
option letter can be given with either uppercase or lowercase letters. 


Files containing a hyphen in the filename must be renamed before use 
with symdeb. Otherwise, symdeb will interpret the hyphen as an 
option designator. 


5.4.2 Specifying Symbol Files 


To debug a Windows application symbolically, you should load symbol 
files for the following items: 

e The application 

e Windows kernel, user, and GDI libraries 

e Other Windows libraries used by the application 
The symbol file for the application is required. The symbol files for the 
Windows libraries are optional, but recommended. They are helpful when 


trying to trace calls made to routines that are not in the application or to 
trace window messages. 


You must give the complete filename and extension when naming a symbol 
file. If the symbol file is not in the current directory, you must supply a 
full pathname. All symbol files must be specified before the win.com file. 
You should always name the application’s symbol file before any other 
symbol files. This ensures that the application’s symbol file is open and 


that you can access the application’s symbols when you first start 
symdeb. 


Example 


symdeb \app\test.sym user.sym gdi.sym \app\testlib.sym win.com 
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Note 


The Windows symbol files for the kernel, user, and GDI libraries, 
kernel.sym, user.sym, and gdi.sym, are provided as part of the Micro- 
soft Windows Software Development Kit. 


You can create symbol files for other Windows libraries by using the 
same methods you used to create application symbol files. 


5.4.3 Passing the Application to Windows 


You can pass the name of your application to Windows by placing the full 
pathname on the symdeb command line immediately after the win.com 
filename. Windows receives the name as an argument when you start 
win.com from within symdeb. Windows uses the name to load and run 
the application. 


Example 


symdeb \app\test.sym win.com \app\test.exe 


If you do not supply your application’s name as an argument, you can load 
and start your application by starting win.com and using the MS-DOS 
Executive to load the application. 


5.4.4 Symdeb Keys 


The symdeb utility provides a number of special keys for controlling 
input and output and program execution. The following is a list of these 
keys: 


Key Action 


SCROLL LOCK Suspends and restores symdeb output. The key is 
typically used to temporarily stop the output of 
lengthy displays. To suspend output, press the SCROLL 
LOCK key. To restore output, press the key again. 


SYS REQ Generates an immediate breakpoint that halts pro- 
ram execution and returns control to symdeb. 


Available on the IBM PC AT only.) 
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CONTROL+C Cancels the current symdeb command. This key com- 
bination does not apply to commands that pass execu- 
tion contro! to the application being debugged. 


5.5 Working with Symbol Maps 


Symbol files that symdeb has loaded for debugging are called symbol 
maps. The symdeb utility lets you examine symbol maps and use the 
symbols in the maps to set breakpoints and display variables and func- 
tions. 


Although symbol maps are in memory, symdeb allows access to only one 
symbol map at a time. You can display a list of symbol maps at any time, 
but to display or use the symbols in a map, you must first open that map. 


Note 


The symdeb utility requires that the filename part of the application’s 
.sym file be the same as the application’s module name (specified in the 
application’s module-definition file). If these names are not identical, 
symdeb will not be able to determine the correct segment addresses 
for symbols in the application. 


5.5.1 Listing the Symbol Maps 


You can display a list of the symbol maps by using the x command with 
the asterisk (*) argument. The command displays the names of all maps in 
memory, the name of each segment belonging to a map, and the 16-bit 
paragraph address of each segment. (The x command without an argu- 
ment displays only the open map.) 


Example 


- xX & 
[ 0000 TEST ] 
[ 0001 IGROUP ] 
0002 DGROUP 
0000 TESTLIB 
0001 _TEXT 
0002 DGROUP 
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The open map name is enclosed in brackets (| |). The active segment in 
the map is also enclosed in brackets. Segment addresses appear immedi- 
ately before the segment names. 


Note 


Symdeb does not display a segment’s actual segment address until the 
code or data corresponding to that segment has been loaded. If you list 
the symbol maps before loading an application, symdeb displays low- 
memory addresses as a warning that the segments are not yet in 
memory. 


Once an application 1s loaded, symdeb appends a number to the end of 
the data-segment name in the symbol map. This number shows which 
instance of the application the data segment belongs to. If you load 
multiple instances of an application, symdeb adds a new data-segment 
name to the symbol map for that application. 


In the following example, symdeb places parentheses around the active 
data segment to show which instance of the application is currently run- 
ning. 


[ 0000 TEST ] 
[ 88FO IGROUP ] 
( 87EO DGROUP ) 

8944 DGROUP1 


5.5.2 Opening a Symbol Map 

To access the symbols in a symbol map, you must open the symbol map 
using the xo command. For example, to open the symbol map named test, 
you would type the following: 


-xo test! 


The symdeb utility opens the symbol map and lets you examine and use 
symbols from the map. 


You can use the xo command to open a different symbol map at any time. 


Since only one symbol map can be open at a time, the previous symbol 
map 1s closed. 
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Note 


When you load multiple symbol maps, symdeb automatically opens 
the first one loaded. 


5.5.3 Display Symbols 


You can use the x? command to display the symbols in the open symbol 
map. The command lists each symbol by name and also gives the symbol’s 
address offset. For example, to display the symbol “testwndproc,” you 
would type the following: 


-x? testwndproc 
[ 88EO IGROUP ] 
OOSA TESTWNDPROC 


The command displays the name and address of the segment to which the 
symbol belongs. The symbol’s absolute address can be computed using the 
segment’s address and the symbol’s offset. In the preceding example, the 

function “testwndproc” is in the segment IGROUP at address 88E0:005A. 


If the symbol is an external symbol (for example, a function or variable 
defined outside of the application), no group name is given and the offset is 
always zero, as shown in the following example: 


-x? showwindow 
0000 SHOWWINDOW 


You can use the asterisk (+) as a wildcard character with the x command 
to display more than one symbol at a time. For example, the following 
command displays all symbols in the IGROUP segment: 


“x? igroup:* 


The following command displays all symbols in the DGROUP segment 
that begin with an underscore (_ ): 


-x? dgroup:_* 
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5.6 Starting the Application 


You can start the application by using the g command. The command 
directs symdeb to pass execution control to the program at the current 
code address. (Immediately after starting symdeb with Windows, the 
current code address is the start address of the win.com file.) 


If you have supplied your application’s filename as a win.com argument on 
the symdeb command line, win.com starts your application automati- 
cally. Otherwise, it starts MS-DOS Executive, which you can use to load 
and run your application. 


5.7 Allocation Messages 


The symdeb utility displays memory-allocation messages to show that 
Windows has created, freed, or moved memory blocks. The messages are 
intended to help you locate your application’s program code and data in 
memory. The messages can also be used to see the effect of the application 
on Windows memory management. The symdeb utility actually displays 
messages only if the memory-allocation reporting level is set to an 
appropriate value (see the /w option in Section 5.4.1). 


When Windows allocates a new block of memory and the reporting level is 
1 or 3, symdeb displays a message of the following form: 


module-name! segment-name=segment-address 

The module-name field specifies the name of the application or library to 
receive the allocated memory. The segment-name field specifies the name of 
the code or data segment within the application or library that will occupy 
the memory block. The segment-address field specifies the 16-bit paragraph 
address of the memory block. 


When Windows moves a block of memory and the reporting level is 2 or 3, 
symdeb displays a message of the following form: 


old-address moved to new-address 


The old-address and new-address fields specify the old and new 16-bit para- 
graph addresses of the memory block. 


When Windows frees a block of memory and the reporting level is 1 or 3, 
symdeb displays a message of the following form: 


segment-address freed 
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The segment-address field specifies the 16-bit paragraph address of the 
block to be freed. 


Example 


TEST! [TGROUP=886F 
TEST !DGROUP=8799 
GDI ! Code=1C32 

8344 moved to 8230 
7C12 freed 


5.7.1 Setting Breakpoints with Symbols 


You can use the bp command and symbols to set breakpoints in your 
application code even before loading the application. The bp command 
uses the symbol to compute the instruction address at which to break exe- 
cution. If the application has not been loaded, symdeb sets a virtual 
breakpoint. A virtual breakpoint has no effect on execution until the appli- 
cation is actually loaded. Once an application is loaded, symdeb com- 
putes the actual code addresses of all virtual breakpoints and enables the 
breakpoints. 


For example, to set a breakpoint at the application’s WinMain function, 
you would type the following: 


-bp winmain 


After you set the breakpoint, the application breaks and returns control to 
symdeb when this address is encountered. 


Note 


If you do not set breakpoints before starting the application, you can 
use an interrupt key to break execution (see Section 5.4.4 for more 
information on symdeb keys). 


5.7.2 Displaying Variables 


You can use the d command to display the content of the application’s 
static variables. The command takes the variable’s symbol as an argument 
and computes the variable’s address using the address of the variable’s 
segment and its offset. The symbol map containing the symbol must be 
open. 
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Example 


-dw hinstance 
8882:0010 0143 0000 0000 0000 0000 C000 COC00O O00D 


When there are multiple instances of the application being debugged, 
symdeb uses the address of the active data segment to compute a 
variable’s address. To display a variable in another instance, you must 
supply an absolute segment address. For example, to display the value of 
hInstance in the first instance, the 16-bit paragraph address of the first 
DGROUP segment must be given explicitly, as shown in the following 
example: 


-x 
[ 0000 TEST j 
[ 8A12 IGROUP ] 
89A0 DGROUP 
( 8882 DGROUP1 ) 
-dw 89A0:hinstance 
88A0:0010 0235 0000 0000 0000 0000 OOOO OOOO OO0D 


5.7.3. Displaying Application Source Statements 


You can display the source statements of an application by using the v, 
s+, and s& commands. The v command displays the source lines of the 
application beginning with the source line corresponding to the current 
code address (cs:ip). The s+ command directs symdeb to display source 
lines whenever the u command is used. The s& command directs symdeb 
to display both source lines and unassembled code whenever the u com- 
mand is used. For more information on these commands, see Section 5.9. 


Note 


If a symbol file does not contain line-number information, the v, s+, 
and s& commands have no effect. 


If the application source file is not in the current directory, or the file 
does not have the same name as the symbol file, symdeb prompts for 
the file’s correct name and/or pathname. 
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5.8 Quitting Symdeb 


You can terminate symdeb at any time by using the q command to return 
to the DOS prompt. Before quitting symdeb, however, you may need to 
end the current Windows session and restore the console display to its nor- 
mal display modes. 


Follow these general rules: 


e If you have not started Windows, use the q command to quit. 


e Ifyou have started Windows and it is still operational, open the 
MS-DOS Executive window and choose the Close command from 
its system (Control) menu, then use the q command. 


Important 


When Windows terminates as a result of a fatal exit, symdeb displays 
a fatal-exit message and returns the symdeb prompt. Do not attempt 
to restart Windows or quit symdeb. You must reboot the system to 
continue. 


5.9 Symdeb Commands 


This section contains a complete listing of commands that can be used 
with symdeb. It also describes the arguments and expressions used with 
symdeb commands, as well as predefined names used as register and 
register-flag names. The following Table 5.1 is a summary of symdeb 
command syntax and purpose: 


Table 5.1 

Symdeb Commands 

Syntax Meaning 
a [address] Assemble 


ba [mode] {[sizel]address| value] command-string] | Sets address breakpoint(s) 
on 80386 machines. 


be [¢d-lisé] Clear breakpoint(s) 
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Table 5.1 (continued) 
Syntax 


bd [7d-list] 

be [¢d-lis¢] 

bl 

bp|id] address [value] |command-string] 
c range address 

d |rangel 


da [range] 
db [range] 
dd jrange] 
dg 
dh 


dl [range] 


dq 
ds [range] 


dt [range] 

dw [range] 

e address [list] 

ea address [list] 

eb address [list] 

ed address [lis¢] 

el address [list] 

es address [list] 

et address [lisé] 

ew address [list] 

f range list 

g |==address |address\... | 
h value value 

i value 

k [value] 

kt pdb | value] 

| [address [drive record count] 
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Meaning 


Disable breakpoint(s) 
Enable breakpoint(s) 
List breakpoint(s) 
Set breakpoint 
Compare 


Dump memory using 
previous type 


Dump memory ASCII 

Dump memory bytes 

Dump memory double-words 
Display global heap 


Display local heap for 
current ds 


Dump memory, long floating 
point 


Display task queue 


Dump memory, short 
floating point 


Dump memory ten-byte reals 
Dump memory words 
Enter using previous type 
Enter ASCII 

Enter bytes 

Enter double-words 
Enter long floating point 
Enter short floating point 
Enter ten-byte reals 
Enter words 

Fill 

Go 

Add hexadecimal 

Input from port 
Backtrace stack 
Backtrace task 

Load 
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Table 5.1 (continued) 


Syntax Meaning 

m range address Move 

mid|—=command-string] Define or execute macro 

n filename [filename...| Set name 

o value byte Output to port 

p [= address] [value] Trace program instruction or call 
q Quit 

r [register] | [==] value] Register 

s range list Search 


aes 
s& 

s+ 

t [= address] [value] 
u [range 

v [range 


w address [drive record count]] 
x |?] symbol 

xo symbol 

z symbol value 

? expression 

< filename 

> filename 

= filename 

{ filename 

} filename 

~ filename 

! [dos-command] 
* string 


Set machine debugging only 

Set machine and source debugging 
Set source debugging only 

Trace program instruction 
Display unassembled instructions 
View source lines 

Write to disk 

Examine symbols(s) 

Open map/segment 

Set symbol value 

Compute and display expression 
Display current source line 
Redirect symdeb input 

Redirect symdeb output 


Redirect symdeb input and output 


Redirect program input 
Redirect program output 


Redirect program input and output 


Shell escape 
Comment 
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Any combination of uppercase and lowercase letters may be used in com- 
mands and arguments. If a command takes two or more parameters, 
separate them with a single comma (,) or one or more spaces. 


Examples 


ds _avg L 10 
U «22 
f DS:100,110 ff, fe,O1,00 


5.9.1 Command Arguments 


Command arguments are numbers, symbols, line numbers, or expressions 
used to specify addresses or values to be used by symdeb commands. The 
following is a list of argument syntax and meaning: 


Argument Description 


address Specifies absolute, relative, or symbolic address of a 
variable or function. The symdeb utility permits a 
wide variety of address types. See Section 5.9.2 for a 
complete description of address arguments. 


byte Specifies a value argument representing a byte value. 
It must be in the range 0 to 255. 


command-string Specifies one or more symdeb commands. If more 
than one command is given, they must be separated by 
semicolons (;). 


count Specifies a value argument representing the number of 
disk records to read or write. 

dos-command Specifies a DOS command. 

drive Specifies a value argument representing a disk drive. 
Drives are numbered zero for A, 1 for B, 2 for C, and 
so on. 

expression Specifies a combination of arguments and operators 


that represents a single value or address. See Section 
5.9.3 for a list and explanation of expression opera- 
tors. 


filename Specifies the name of a file or a device. The file- 
name must follow the DOS file-naming conventions. 
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1d 


1d-list 


list 


range 


record 


register 
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Specifies a decimal number representing a breakpoint 
or macro identifier. The number must be in the range 
0 to 9. 


Specifies one or more unique decimal numbers 
representing a list of breakpoint identifiers. The 
numbers must be in the range O to 9. If more than one 
number is given, they must be separated using spaces 
or commas. The wildcard character (*) can be used to 
specify all breakpoints. 


Specifies one or more value arguments. The values 
must be in the range 0 to 65,535. If more than one 
value is given, they must be separated using spaces or 
commas. 


A list can also be specified as a list of ASCII values. 
The list can contain any combination of characters 
and must be enclosed in either single or double quota- 
tion marks. If the enclosing mark appears within the 
list, it must be given twice. 


Specifies an address range. Address ranges have two 
forms: a start and end address pair and a start address 
and object count. The first form consists of two 
address arguments, the first specifying the start 
address and the second specifying the end address. 
The second form consists of an address argument, the 
letter 1, and a value argument. The address specifies 
the starting address; the value specifies the number of 
objects after the address to examine or display. The 
size of an object depends on the command. If a com- 
mand requires a range but only a start address is given 
in the command, the command assumes the range to 
have an object count of 128. This default count does 
not apply to commands that require a range followed 
immediately by a value or an address argument. 


Specifies a value argument representing the first disk 
record to be read or written to. 


Specifies the name of a CPU register. It can be any one 
of the following: 


ax cx es si 

bp di f sp 
bx ds ip ss 
cs dx pc 


The names ip and pe name the same register: the 
instruction pointer. The name f is a special name for 
the flags register. Each flag within the flags register 
has a unique name based on its value. These names 


symbol 


pdb 


value 


Symbolic Debugging Utility: Symdeb 


can be used to set or clear the flag. Table 5.2 lists the 
flag names: 


Table 5.2 

Flag Values 

Flag Set Clear 
Overflow OV nv 
Direction dn (decrement) up (increment) 
Interrupt ei (enabled) di (disabled) 
Sign ng (negative) pl (positive) 
Zero ar nz 
Auxiliary Carry ac na 

Parity pe (even) po (odd) 
Carry cy ne 


Identifies the address of a variable, function, or seg- 
ment. A symbol consists of one or more characters, 
but always begins with a letter, underscore (_ ), ques- 
tion mark (?), at symbol (@), or dollar sign ($). 
Symbols are only available when the .sym file that 
defines their names and values has been loaded. Any 
combination of uppercase and lowercase letters can be 
used; symdeb is not case-sensitive. For some com- 
mands, the wildcard character (+) may be used as part 
of a symbol to represent any combination of charac- 
ters. 


Specifies a value argument representing the segment 
address of a program descriptor block. 


Specifies an integer number in binary, octal, decimal, 
or hexadecimal format. A value consists of one or more 
digits optionally followed by a radix: Y for binary, O 
or Q for octal, T for decimal, or H for hexadecimal. If 
no radix is given, hexadecimal is assumed. Symdeb 
truncates leading digits if the number is greater than 
65,535. Leading zeroes, if any, are ignored. Hexade- 
cimal numbers have precedence over symbols. Thus 
FAA is a number. 
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5.9.2 Address Arguments 


Address arguments specify the location of variables and functions. The 
following list explains the syntax and meaning of the various addresses 
used in symdeb: 


Syntax Meaning 
segment:offset Specifies an absolute address. A full address 


has both a segment address and an offset, 
separated by a colon (:). A partial address is 
just an offset. In both cases, the segment or 
offset can be any number, register name, or 
symbol. If no segment is given, the a, g, l, p, 
t, u, and w commands use the cs register for 
the default segment address. All other com- 
mands use ds. 


name{ + | —} offset Specifies a symbol-relative address. The name 
can be any symbol. The offset specifies the 
offset in bytes. The address can be specified as 
a positive (+) or negative (—) offset. 


+ | —} number _ Specifies a relative line number. The number 
is an offset (in lines) from the current source 
line to the new line. If + is given, the new line 
is closer to the end of the source file. If — is 
given, the new line is closer to the beginning. 


.[filename:] number Specifies an absolute line number. If filename 
is given, the specified line is assumed to be in 
the source file corresponding to the symbol 
file identified by filename. If no filename is 
given, the current instruction address (the 
current values of the cs and ip registers) 
determines which source file contains the line. 


.symbol|{+ }—}number]| Specifies a symbolic line number. The symbol 
: can be any instruction or procedure label. If 
number is given, the number is an offset (in 
lines) from the given label or procedure name 
to the new line. If + is given, the new line is 
closer to the end of the source file. If — is 
given, the new line is closer to the beginning. 


Note 


Line numbers can be used only with programs developed with com- 
pilers that copy line-number data to the object file. 
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5.9.3 Expressions 


An expression is a combination of arguments and operators that evaluates 
to an 8-, 16-, or 32-bit value. Expressions can be used as values in any 
command. 


An expression can combine any symbol, number, or address with any of 
the unary and binary operators in the following Tables 5.3 and 5.4: 


Table 5.3 
Unary Operators 
Operator Meaning Precedence 
a Unary plus Highest 
— Unary minus 
not \’s complement 
seg Segment address of operand 
off Address offset of operand 
by Low-order byte from given address 
wo Low-order word from given address 
dw Double-word from given address 
pol Pointer from given address 
a as dw) 
port ne byte from given port 
wport Word from given port Lowest 
Table 5.4 
Binary Operators 
Operator Meaning Precedence 
. Multiplication Highest 
/ Integer division 
mod Modulus 
: Segment override 
+ Addition 
— Subtraction 
and Bitwise Boolean AND 
xor Bitwise Boolean exclusive OR 
or Bitwise Boolean OR | Lowest 


Unary address operators assume ds as the default segment for addresses. 
Expressions are evaluated in order of operator precedence. If adjacent 
operators have equal precedence, the expression is evaluated from left to 
right. Parentheses can be used to override this order. 
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Examples 

SEG 0001:0002 ; Equals 1 

OFF 0001 :0002 ; Equals 2 

4+2%3 : Equals 10 (OAh) 

4+ (2%3) : Equals 10 (OAh) oN 
(4+2) %3 : Equals 18 (12h) 


5.9.4 Assemble Command 


Syntax 


aladdress| 


This command assembles instruction mnemonics and places the resulting 
instruction codes into memory at address. If no address is given, the assem- 
bly starts at the address given by the current values of the cs and ip regis- 
ters. To assemble a new instruction, type the desired mnemonic and press 
the ENTER key. To terminate assembly, press the ENTER key only. There 
are the following assembly rules: 


Use retf for the far return mnemonic. 
Use movsb or movsw for string-manipulation mnemonics. 


Use the near or far prefix with labels to override default distance. 
The ne abbreviation stands for near. 


Use the word ptr or byte ptr prefix with destination operands to 
specify size. The wo abbreviation stands for word ptr; by for 
byte ptr. 


Use square brackets around constant operands to specify absolute 
memory addresses. Constants without brackets are treated as 
constants. 


Use the db mnemonics to assemble byte values or ASCII strings 
directly into memory. 


Use 8087 or 80287 instructions only if your system has these math 
coprocessors. 


80286 protected-mode mnemonics cannot be assembled. 
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5.9.5 Breakpoint Address Command 


Syntax 
ba option size address [value] |command-string] 


This command, used with 80386 machines, sets an address breakpoint at a 
given address. If your program accesses memory at this address, symdeb 
will stop execution and display the current values of all registers and flags. 
There are three types of breakpoints you can set with the option parame- 
ter. Since the breakpoint address is a physical address, breakpoints should 
not be set for memory that might be moved (though you can temporarily 
lock the segment for the purpose of debugging). If I is specified, symdeb 
takes a breakpoint when the CPU fetches an instruction from the given 
address. \f R is specified, symdeb takes a breakpoint when the CPU reads 
a byte, word, or double-word from the given address. If U is specified, 
symdeb takes a breakpoint when the CPU reads or writes a byte, word, 
or double-word to the given address. 


The szze parameter specifies the size of the data that symdeb expects to 
find read or written at the given address; the breakpoint will be taken only 
if the data has that size. If B is specified (8-bit byte), the command will 
break only at one address (for example, 0:10). If W is specified (16-bit 
word), the command will break at one of two addresses within that range 
(for example, 0:10 or 0:11 will cause a break within that word). If D is 
specified (32-bit double-word), the command will break at one of four 
addresses within that range (for example, 0:08, 0:09, 0:10, or 0:11 will 
cause a break within that double-word). 


The address parameter can specify any valid address. The address value 

is rounded down if necessary to the nearest byte, word, or double-word 
boundary (for example, if a double-word address of 0:14 was requested, the 
command would access the address of the nearest double-word boundary 
below the address, in this case 0:12). 


The optional value parameter specifies the number of times the breakpoint 
is to be ignored before being taken. It can be any 16-bit value. 


The command-string parameter specifies an optional list of commands to 
be executed each time the breakpoint is taken. Each symdeb command in 
the list can include parameters and is separated from the next command 
by a semicolon. 


The be, bd, be, and bl commands can all be used on these breakpoints. 
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5.9.6 Breakpoint Clear Command 


Syntax 

be id-list 

This command permanently removes one or more previously set break- 
points. If zd-list is given, the command removes the breakpoints named in 


the list. The zd-lzst can be any combination of integer values from 0 to 9. If 
the wildcard character (*) is given, the command removes all breakpoints. 


5.9.7 Breakpoint Disable Command 


Syntax 
bd td-list 
This command disables, but does not delete, one or more breakpoints. If 
id-list is given, the command disables the breakpoints named in the list. 


The zd-list can be any combination of integer values from 0 to 9. If the 
wildcard character (*) is given, the command disables all breakpoints. 


5.9.8 Breakpoint Enable Command 


Syntax 
be ¢d-list 


This command restores one or more breakpoints that were temporarily 
disabled by a bd command. If zd-lest is given, the command enables the 
breakpoints named in the list. The zd-list can be any combination of 
integer values from 0 to 9. If the wildcard character (*) is given, the com- 
mand enables all breakpoints. 
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5.9.9 Breakpoint List Command 


Syntax 
bi 


This command lists current information about all breakpoints. The com- 
mand displays the breakpoint number, the enabled status, the address of 
the breakpoint, the number of passes remaining, and the initial number of 
passes (in parentheses). The enable status can be enabled (e), disabled (d), 
or virtual (v). A virtual breakpoint is a breakpoint set at a symbol whose 
.exe file has not yet been loaded. 


5.9.10 Breakpoint Set Command 


Syntax 
bp|id] address [value] [command-string] 


This command creates a “sticky” breakpoint at the given address. Sticky 
breakpoints stop execution and display the current values of all registers 
and flags. Sticky breakpoints remain in the program until removed using 
the be command, or temporarily disabled using the bd command. The 
symdeb utility allows up to ten sticky breakpoints (0 through 9). The 
optional zd parameter specifies which breakpoint is to be created. If no zd 
is given, the first available breakpoint number is used. The address param- 
eter can be any valid instruction address (that is, it must be the first byte 
of an instruction). The optional value parameter specifies the number of 
times the breakpoint is to be ignored before being taken. It can be any 16- 
bit value. The optional command-string parameter specifies a list of com- 
mands to be executed each time the breakpoint is taken. Each symdeb 
command in the list can include parameters and is separated from the next 
command by a semicolon (;). 


5.9.11 Compare Command 


Syntax 
ce range address 


This command compares the bytes in the memory locations specified by 
range with the corresponding bytes in the memory locations beginning 

at address. If all corresponding bytes match, the command displays its 
prompt and waits for the next command. If one or more corresponding 
bytes do not match, the command displays each pair of mismatched bytes. 
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5.9.12 Dump Command 


Syntax 
d [range] 


This command displays the contents of memory in the given range. The 
command displays data in the same format as the most recent dump com- 
mand. (Dump commands include d, da, db, dd, dg, dh, dl, dq, ds, dt, 
and dw.) If no range is given and no previous dump command has been 
used, the command displays bytes starting from ds:ip. 


5.9.13 Dump ASCII Command 


Syntax 
da [range] 


This command displays the ASCII characters in the given range. Each line 
displays up to 48 characters. The display continues until the first null byte 
or until all characters in the range have been shown. Nonprintable charac- 
ters, such as carriage returns and line feeds, are displayed as periods (.). 


5.9.14 Dump Bytes Command 


Syntax 
db [range] 


This command displays the hexadecimal and ASCII values of the bytes in 
the given range. Each display line shows the address of the first byte in the 
line, followed by up to 16 hexadecimal byte values. The byte values are 
immediately followed by the corresponding ASCII values. The eighth and 
ninth hexadecimal values are separated by a hyphen (-). Nonprintable 
ASCII values are displayed as periods (.). 
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5.9.15 Dump Double-Words Command 


Syntax 

dd [range] 

This command displays the hexadecimal values of the double-words (4- 
byte values) in the given range. Each display line shows the address of the 


first double-word in the line and up to four hexadecimal double-word 
values. 


5.9.16 Display Global Heap Command 


Syntax 
dg 


This command displays a list of the global memory objects in the global 
heap. The list has the following form: 


segment-address: size segment-type owner 

The segment-address field specifies the segment address of the first byte 
of the memory object. The szze field specifies the size in paragraphs 
(multiples of 16 bytes) of the object. The segment-type field specifies the 
type of object. The type can be any one of the following: 


Segment Type Meaning 


CODE Segment contains program code. 

DATA Segment contains program data and possible stack 
and local heap. 

PRIV Segment contains private data. 

FREE Segment belongs to pool of free memory objects ready 
for allocation by an application. 

SENTINAL Segment marks the beginning or end of the global 
heap. 


The owner field specifies the module name of the application or library 
that allocated the memory object. The name PDB is used for memory 
objects that represent program descriptor blocks. These blocks contain 
execution information about applications. 
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5.9.17 Display Local Heap Command 


Syntax 

dh 

This command displays a list of the local memory objects in the local heap 
(if any) belonging to the current data segment. The command uses the 


current value of the ds register to locate the data segment and check for a 
local heap. The list of memory objects has the following form: 


offset: size { BUSY | FREE } 

The offset field specifies the address offset from the beginning of the data 
segment to the local memory object. The szze field specifies the size of the 
memory object in bytes. If BUSY is given, the object has been allocated 

and is currently in use. If FREE is given, the object is in the pool of free 


objects ready to be allocated by the application. A special memory object, 
SENTINAL, may also be displayed. 


5.9.18 Dump Long Reals Command 


Syntax 

dl [range] 

This command displays the hexadecimal and decimal values of the long 
(8-byte) floating-point numbers in the given range. Each display line shows 


the address of the floating-point number, the hexadecimal values of the 
bytes in the number, and the decimal value of the number. 


5.9.19 Dump Task Queue Command 


Syntax 
dq 


This command displays a list containing information about the various 
task queues supported by the system. 
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5.9.20 Dump Short Reals Command 


Syntax 

ds [range] 

This command displays the hexadecimal and decimal values of the short 
(4-byte) floating-point numbers in the given range. Each display line shows 


the address of the floating-point number, the hexadecimal values of the 
bytes in the number, and the decimal value of the number. 


5.9.21 Dump Ten-Byte Reals Command 


Syntax 

dt [range] 

This command displays the hexadecimal and decimal values of the ten- 
byte floating-point numbers in the given range. Each display line shows 


the address of the floating-point number, the hexadecimal values of the 
bytes in the number, and the decimal value of the number. 


5.9.22 Dump Words Command 


Syntax 
dw [range] 
This command displays the hexadecimal values of the words (2-byte 


values) in the given range. Each display line shows the address of the first 
word in the line and up to eight hexadecimal word values. 


5.9.23 Enter Command 


Syntax 
e address [list] 


This command enters one or more values into memory. The size of the 
value entered depends on the most recently used enter command. (Enter 
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commands are e, ea, eb, ed, el, es, et, and ew.) The default is eb (bytes). 
If no list is given, the command displays the value at address and prompts 
for a new value. If lst is given, the command replaces the value at address 
and at each subsequent address until all values in the list have been used. 


5.9.24 Enter Address Command 


Syntax 
ea address [list] 


This command enters an ASCII string into memory. If no lst is given, the 
command displays the byte at address and prompts for a replacement. If 
list is given, the command replaces the bytes at address, then displays the 
next byte and prompts for a replacement. 


5.9.25 Enter Bytes Command 


Syntax 
eb address |lisé] 


This command enters one or more byte values into memory. If list is given, 
the command replaces the byte at address and bytes at each subsequent 
address until all values in the list have been used. If no lust is given, the 
command displays the byte at address and prompts for a new value. To 
skip to the next byte, enter a new value or press the SPACEBAR. To move 
back to the previous byte, type a hyphen (—). To exit from the command, 
press the ENTER key. 


5.9.26 Enter Double-Words Command 


Syntax 
ed address | value] 


This command enters a double-word value into memory. If no value is 
given, the command displays the double-word at address and prompts for 
a replacement. If value is given, the command replaces the double-word at 
address, then displays the next double-word and prompts for a replace- 
ment. Double-words must be typed as two words separated by a colon. 
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5.9.27 Enter Long Reals Command 


Syntax 
el address [value] 


This command enters a long-real value into memory. If no value is given, 
the command displays the long-real value at address and prompts for a 
replacement. If value is given, the command replaces the long-real value at 
address, then displays the next long-real value and prompts for a replace- 
ment. 


5.9.28 Enter Short Reals Command 


Syntax 
es address | value] 


This command enters a short-real value into memory. If no value is given, 
the command displays the short-real value at address and prompts for a 
replacement. If value is given, the command replaces the short-real value 
at address, then displays the next short-real value and prompts for a 
replacement. 


5.9.29 Enter Ten-Byte Reals Command 


Syntax 
et address | value] 


This command enters a ten-byte real value into memory. If no value is 
given, the command displays the ten-byte real value at address and 
prompts for a replacement. If value is given, the command replaces the 
ten-byte real value at address, then displays the next ten-byte real value 
and prompts for a replacement. 
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5.9.30 Enter Words Command 


Syntax 
ew address [value] 


This command enters a word value into memory. If no value is given, 
the command displays the word at address and prompts for a replacement. 
If value is given, the command replaces the word at address, then displays 
the next word and prompts for a replacement. 


5.9.31 Fill Command 


Syntax 
f range list 


This command fills the addresses in the given range with the values in /ast. 
If range specifies more bytes than the number of values in the list, the list 
is repeated until all bytes in the range are filled. If /zst has more values 
a the number of bytes in the range, the command ignores any extra 
values. 


5.9.32 Go Command 


Syntax 
g |==startaddress| |breakaddress|... 


This command passes execution control to the program at the given start- 
address. Execution continues to the end of the program or until break 
address is encountered. The program also stops at any breakpoints set 
using the bp command. If no startaddress is given, the command passes 
execution to the address specified by the current values of the cs and ip 
registers. If breakaddregs is given, it must specify an instruction address 
(that is, the address must contain the first byte of an instruction). Up to 
ten break addresses, in any order, can be given at one time. 
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5.9.33 Hex Command 


Syntax 
h valuel value? 


This command displays the sum and difference of two hexadecimal 
numbers, value1 and value2. 


5.9.34 Input Command 


Syntax 
i value 


This command reads and displays one byte from the input port specified 
by value. The value parameter can specify any 16-bit port address. 


5.9.35 Backtrace Stack Command 


Syntax 
k [value] 


This command displays the current stack frame. Each line shows the name 
of a procedure, its arguments, and the address of the statement that called 
it. The command displays two 2-byte arguments by default. If value is 
given, the command displays that many 2-byte arguments. Using the k 
command at the beginning of a function (before the function prolog has 
been executed) may give incorrect results. The command uses the bp regis- 
ter to compute the current backtrace, and this register is not correctly set 
for a function until its prolog has been executed. 


5.9.36 Backtrace Task Stack Command 


Syntax 

kt pdb |[valuel 

This command displays the stack frame of the program specified by pdb. 
Each line shows the name of a procedure, its arguments, and the address 


of the statement that called it. The command displays two 2-byte argu- 
ments by default. If value is given, the command displays that many 2- 
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byte arguments. The pdb parameter must specify the segment address of 
the program descriptor block for the task to be traced. 


5.9.37 Load Command 


Syntax 
1 [address [drive record count|| 


This command copies the contents of a named file or the contents of a 
given number of logical disk records into memory. The contents are copied 
to address or to a default address, and the bx:cx register pair 1s set to the 
number of bytes loaded. 


To load a file, set the filename using the n command (otherwise, symdeb 
uses whatever name is currently at location ds:5C). If address is not given, 
symdeb copies bytes to cs:100. 


To load logical records from a disk, set drive to zero (drive A), 1 (drive B), 
or 2 (drive C). Set record to the first logical record to be read (any 1- to 4- 
digit hexadecimal number). Set count to the number of records to read 
(any 1- to 4-digit hexadecimal number). If the named file has a .exe exten- 
sion, the 1 command adjusts the load address to the address given in the 
.exe file header. The command strips any header information from a .exe 
file before loading. If the named file has a .hez extension, the 1 command 
adds that file’s start address to address before loading the file. 


5.9.38 Move Command 


Syntax 
m range address 
This command moves the block of memory specified by range to the loca- 


tion starting at address. All moves are guaranteed to be performed with- 
out data loss. 
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5.9.39 Macro Command 


Syntax 
mid|==command-string] 


This command defines or executes a symdeb command macro. The id 
parameter identifies the macro to be defined or executed. There are ten 
macros, numbered 0 through 9. If command-string is specified, the com- 
mand assigns the symdeb commands given in the string to the macro. If 
no string is given, the command executes the commands currently assigned 
to the macro. Macros are initially empty unless the /@ option is used 
when symdeb is started. This option reads a set of macro definitions from 
a specified file. 


5.9.40 Name Command 


Syntax 
n [filename] [arguments] 


This command sets the filename for subsequent 1 and w commands, or 

sets program arguments for subsequent execution of a loaded program. If 
filename is given, all subsequent 1 and w commands will use this name 
when accessing disk files. If arguments is given, the command copies all 
arguments, including spaces, to the memory location starting at ds:81 and 
sets the byte at ds:80 to a count of the total number of characters copied. 
If the first two arguments are also filenames, the command creates file con- 
trol blocks at addresses ds:5C and ds:6C and copies the names (in proper 
format) to these blocks. 


5.9.41 Output Command 


Syntax 
o value byte 


This command sends the given byte to the output port specified by value. 
The value parameter can specify any 16-bit port address. 
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5.9.42 Program Step Command 


Syntax 
p |= =startaddress| | value] 


This command executes the instruction at startaddress, then displays the 
current values of all registers and flags. If startaddress is given, the com- 
mand starts execution at the given address. Otherwise, it starts execution 
at the instruction pointed to by the current cs and ip registers. If value is 
given, the command executes value number of instructions before stop- 
ping. The command automatically executes and returns from any call 
instructions or software interrupts it encounters, leaving execution control 
at the next instruction after the call or interrupt. 


5.9.43 Quit Command 


Syntax 


q 


This command terminates symdeb execution and returns control to DOS. 
5.9.44 Register Command 


Syntax 
r [register] |=] value] ] 


This command displays the contents of CPU registers and allows the con- 
tents to be changed to new values. 


If no register is specified, the command displays all registers, all flags, and 
the instruction at the address pointed to by the current cs and ip register 
values. If register is specified, the command displays the current value of 
the register and prompts for a new value. If both register and value are 
specified, the command changes the register to the specified value. 
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5.9.45 Search Command 


Syntax 
s range list 


This command searches the given range of memory locations for the byte 
values given in /zst. The command displays the address of each byte found. 


5.9.46 Set Source Mode Commands 


Syntax 


s— 
g& 
s-++ 


These commands set the display mode for commands that display instruc- 
tion code. If s— is given, symdeb disassembles and displays the instruction 
code in memory. If s& is given, symdeb displays both the actual program 
source line and the disassembled code. If s+ is given, symdeb displays 

the actual program source line corresponding to the instruction to be 
displayed. 


To access a source file for the first time, symdeb may display the follow- 
ing prompt: 


Source file name for mapname (cr for none)? 


In such cases, type the name, including extension, of the source file 
corresponding to the symbol file mapname. 


5.9.47 Trace Command 


Syntax 
t [==startaddress] [value] 


This command executes the instruction at startaddress, then displays the 
current values of all registers and flags. If startaddress is given, the com- 
mand starts execution at the given address. Otherwise, it starts execution 
at the instruction pointed to by the current cs and ip registers. If value is 
given, the command continues to execute value number of instructions 
before stopping. In source-only mode (s+), t operates directly on source 
lines. The t command can be used to trace instructions in ROM. 
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5.9.48 Unassemble Command 


Syntax 
u [range| 


This command displays the instructions and/or statements of the program 
being debugged. The s command sets the display format. If range is given, 
the command displays instructions generated from code within the given 
range. Otherwise, the command displays the instructions generated from 
the first eight lines of code at the current address. 80286 protected-mode 
mnemonics cannot be displayed. 


5.9.49 View Command 


Syntax 
Vv range 


This command displays source lines beginning at the specified range. The 
symbol file must contain line-number information. 


5.9.50 Write Command 


Syntax 
w [address [drive record count] 


This command writes the contents of a given memory location to a named 
file, or to a given logical record on disk. To write to a file, set the filename 
with an n command, and set the bx:ex register pair to the number of 
bytes to be written. If no address is given, the command copies bytes start- 
ing from the address cs:100, where es is the current value of the es regis- 
ter. To write to a logical record on disk, set drive to any number in the 
range zero (drive A) to 2 (drive C), set record to the first logical record to 
receive the data (a l- to 4-digit hexadecimal number), and set count to the 
number of records to write to the disk (a 1- to 4-digit hexadecimal 
number). Do not write data to an absolute disk sector unless you are sure 
the sector is free. 
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5.9.51 Examine Symbol Map 


Syntax 
x [*! 2? symbol] 


This command displays the name and load-segment addresses of the 
current symbol map, segments in that map, and symbols within those 
segments. 


If no parameter is given, the command displays the current symbol map 
name and the segments within that map. If the asterisk (*) is specified, the 
command displays the names and load-segment addresses for all currently 
loaded symbol maps. If ? is specified, the command displays all symbols 
within the given symbol map that match the symbol specification. A 
symbol specification has the following form: 


| mapnamel] [segmentname:] [symbolname] 


If mapname! is given, the command displays information for that symbol 
map. The mapname parameter must specify the filename (without exten- 
sion) of the corresponding symbol file. 


If segmentname: is given, the command displays the name and load- 
segment address for that segment. The segmentname parameter must 
specify the name of a segment named within the explicitly given or 
currently open symbol map. 


If symbolname is given, the command displays the segment address and 
segment offset for that symbol. The symbolname parameter must specify 
the name of a symbol in the given segment. 

To display information about more than one segment or symbol, enter a 


partial segmentname or symbolname ending with an asterisk (*). The aster- 
isk acts as a wildcard character. 


5.9.52 Open Symbol Map Command 


Syntax 
xo [symbol!] 
This command sets the active symbol map and/or segment. If symbol! is 


given, the command sets the active symbol map to the given map. The 
symbol parameter must specify the filename (without extension) of one 
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of the symbol files specified in the symdeb command line. A map file can 
be opened only if it was loaded by providing its name in the symdeb com- 
mand line. 


5.9.53 Set Symbol Value Command oe 


Syntax 
z symbol value 


This command sets the address of symbol to value. 
5.9.54 Display Help Command 


Syntax 


? 


This command displays a list of all symdeb commands and operators. 
5.9.55 Display Expression Command 


Syntax 

? expression 

This command displays the value of expression. The display includes a full 
address, a 16-bit hexadecimal value, a full 32-bit hexadecimal value, a 
decimal value (enclosed in parentheses), and a string value (enclosed in 


double quotation marks). The expression parameter can specify any combi- 
nation of numbers, symbols, addresses, and operators. 


5.9.56 Source-Line Display Command 


Syntax 


This command displays the current source line. 
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5.9.57 Redirect Input Commands 


Syntax 


< filename 
{ filename 


The <Q command causes symdeb to read all subsequent command input 
from the given file. The { command reads all input for the debugged pro- 
gram from the given file. 


5.9.58 Redirect Output Commands 


Syntax 


> filename 
} filename 


The > command causes symdeb to write all subsequent command output 
to the given file. The } command writes all output from the debugged pro- 
gram to the given file. | 


5.9.59 Redirect Input and Output Commands 


Syntax 


= filename 
~ filename 


The = command causes symdeb both to read from and to write to the 
device specified in the filename. The ~ command causes the debugged pro- 
gram both to read from and to write to the given device. 


5.9.60 Shell Escape Command 


Syntax 
! | dos-command] 


This command passes control to command.com, the DOS command proces- 
sor, letting the user carry out DOS commands. The DOS exit command 
returns contro! to symdeb. If dos-command is given, symdeb passes the 
command to command.com for execution, then receives control back as 
soon as the command is completed. 


137 


Microsoft Windows Programming Tools 


5.9.61 Comment Command 


Syntax 
* comment 


This command echos comment on the screen (or other output device). 
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6.1 Introduction 


The Microsoft Program Maintenance Utility (make) automates the pro- 
cess of maintaining assembly-language and high-level-language programs. 
The make utility automatically carries out all the tasks that need to be 
done in order to update a program after one or more of its source files 
have changed. 


Unlike other batch-processing programs, make does not assemble, com- 
pile, and link all files just because one file has been updated. The make 
utility compares the last modification date of the file or files that may need 
updating with the modification dates of files on which these target files 
depend. The make utility then carries out the given task only if a target 
file is out of date. This process saves you time when you are creating pro- 
grams that have many source files or that take several steps to complete. 


This chapter explains how to use make and illustrates how to maintain a 
sample assembly-language program. 


6.2 Using Make 


To use make, you must create a make description file that defines the 
tasks you want to accomplish and specifies the files on which these tasks 
depend. Once the description file exists, you invoke make and supply the 
filename as a parameter; make then reads the contents of the file and 
carries out the requested tasks. Sections 6.2.1 and 6.2.2 explain how to 
create a make description file and how to start make. 


6.2.1 Creating a Make Description File 


You can create a make description file with a text editor. A make 
description file consists of one or more target/dependent descriptions. 
Each description has the following general form: 


targetfile: dependentfiles 


command! 
[command9| 


141 


Microsoft Windows Programming Tools 


The targetfile parameter specifies the name of a file that may need updat- 
ing. The dependentfiles parameter specifies the name of a file on which the 
target file depends. 


The names specified by the targetfile and dependentfiies parameters must 
be valid filenames. A pathname must be provided for any file that 1s not on 
the same drive and in the same directory as the description file. 


Any number of dependent files can be given, but only one target name 1s 
allowed. The names of dependent files must be separated from each other 
by at least one space. If you have more dependent filenames than can 

fit on one line, you can continue the names on the next line by typing a 
backslash (\) followed by a new line. 


The command parameter can specify any valid DOS command line, con- 
sisting of the name of an executable filename or a DOS internal command. 
Any number of commands can be given, but each must begin on a new line 
and must be preceded by a tab or by at least one space. The commands | 
are carried out only if one or more of the dependent files has been modified 
since the target file was created. 


Think of the make format as an “if/then” statement: if any dependentfile 
is newer than the targetfile, or if there is no targetfile, then execute com- 
mands. 


You can give any number of target or dependent descriptions in a descrip- 
tion file. You must make sure, however, that the last line in one descrip- 
tion 1s separated from the first line of the next by at least one blank line. 


The number sign (#) is a comment character. All characters after the 
comment character on the same line are ignored. When comments appear 
in a command-line section, the comment character (#) must be the first 
character on the line (no white space should appear before it). On any 
other lines, the comment character can appear anywhere. 


Note 


The order in which you place the target or dependent descriptions 1s 
important. The make utility examines each description in turn and 
bases its decision to carry out a given task on the file’s current modifi- 
cation date. If a command in a later description modifies a file, make 
cannot return to the description in which that file is a dependent. 
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Example 


startup.obj: startup .asm 
masm startup, startup,nul,nul 


print.obj: print.asm 
masm print,print,print, print 


print.ref: print.crf 
cref print,print 


print.exe: startup.obj print.obj \lib\syscal.1lib 
link startuptprint, print, print/map,\lib\syscal; 


print.sym: print .map #make a symbol file for debugging 
#use the -1 option to print information 
mapsym -1 print.map 


This example defines the actions needed to create five target files. Each file 
has at least one dependent file and one command. The target descriptions 
are given in the order in which the target files will be created. Thus, 
startup.obj and print.obj are examined and created, if necessary, before 
print.eze. 


Notice that a comment appears on the same line as the target description 
for print.sym. However, in the command-line section, the comment appears 
on a separate line because the comment character (#) must be the first 
character on the line. 


6.2.2 Starting Make 
Syntax 
make | options] [macrodefinitions] filename 


The options parameter specifies one or more of the options described in 
Section 6.2.3. The macrodefinitions parameter specifies one or more of the 
macro definitions described in Section 6.2.4. The filename parameter 
specifies the name of a make description file. A make description file, by 
convention, has the same filename (but with no extension) as the program 
A describes. Although any filename can be used, this convention is pre- 
erred. 


Once you start make, it examines each target description in turn. If a 
given target file is out-of-date compared to its dependent file or if the tar- 
get file does not exist, make executes the given command or commands. 
Otherwise, it skips to the next target description. 
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When make finds an out-of-date target file, it displays the command or 
commands from the target /dependent description, then executes the com- 
mands. If make cannot find a specified file, it displays a message inform- 
ing you that the file was not found. If the missing file is a target file, make 
continues execution because the missing file will, in many cases, be created 
by subsequent commands. 


If the missing file is a dependent or command file, make stops execution of 
the description file; make also stops execution and displays the exit code 
if the command returns an error. oe can override this by using the /i 
option. See Section 6.2.3 for details.) 


When make executes a command, it uses the same environment used to 
invoke make. Thus, environment variables such as PATH are available for 
these commands. 


6.2.3. Using Make Options 


The options available with the make command modify its behavior and 
are described as follows: 


Option Description 
/d This option causes make to display the last modification 


date of each file as the file 1s scanned. 


fi This option causes make to ignore exit codes (also called 
return or “errorlevel” codes) returned by programs called 
by the make description file. Despite the errors, make will 
continue execution of the next lines of the description file. 


/n This option causes make to display commands that would 
be executed by a description file, but the commands are not 
actually executed. 


/s This option causes make to execute in “silent” mode. That 
is, lines are not displayed as they are executed. 

Examples 

make /n test 


The first example directs make to display commands from the make 
description file named test without executing them. 
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make /d test 


The second example directs make to execute the instructions from test, 
displaying the last modification date of each file as it is scanned. 


6.2.4 Using Macro Definitions 


Macro definitions allow you to associate a symbolic name with a particular 
value. By using macro definitions, you can change values in the description 
file without having to edit every line that contains a particular value. 


A macro definition has the following form: 

name= value 

The form for using a previously defined macro definition is as follows: 
$ (name) 


Occurrences of the pattern $(name) in the description file are replaced 
with the specified value. The name parameter is converted to uppercase: 
“flags” and “FLAGS” are equivalent. If you define a macro name but leave 
the value parameter blank, value will be a null string. 


Macro definitions can be placed in the make description file or given on 
the make command line. A name parameter is also considered defined if it 
has a definition in the current environment. For example, if the environ- 
ment variable PATH is defined in the current environment, occurrences of 
“$(PATH)” in the description file will be replaced with the PATH value. 


In the make description file, each macro definition must appear on a 
separate line. Any white space (tab and space characters) between name 
and the equal sign (=) or between the equal sign and value is ignored. Any 
other white space is considered part of value. To include white space in a 
macro definition on the command line, enclose the entire definition in 
double quotation marks (" "). 


If the same name is defined in more than one place, the following order of 
precedence applies: 


1. Command-line definition 
2. Description-file definition 
3. Environment definition 
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Example 


BASE=abc 
BUF=/B63 


$ (BASE) .obj: $ (BASE) .asm Cs 
masm $(BASE) $ (BUF) ,§$ (BASE) ,$ (BASE) , $ (BASE) 


$ (BASE) .exe: $ (BASE) .obj \lib\math.1lib 
link $(BASE),$(BASE),8(BASE) /map, \lib\math 


The preceding example of a make description file shows macro defini- 
tions for the names “BASE” and “BUF”. The make utility replaces each 
occurrence of “$(BASE)” with “abc”. 


If the description file is called assemble, you can give the following 
command: 


make BASE=def assemble 


This command line enables you to override the definition of “BASE” in the 
description file, causing “def” to be assembled and linked instead of “abc”. 


If you want to override the 63K buffer size specified by the macro “BUF” 
in the make description file and instead use the masm default buffer size 
of 32K, you can start make with the following command line: 


make BUF=assemble 

Since the value for “BUF” is blank, it will be treated as a null string. How- 
ever, since the null string was given from the command line, which has 
higher precedence than the definition in the description file, “BUF” will be 


expanded to a null string and no option will be passed in the masm com- 
mand line. 


6.2.5 Nesting Macro Definitions 

Macro definitions can be nested. In other words, a macro definition can 
include another macro definition. For example, you might have the follow- 
ing macro definition in the make description file picture: 
LIBS=$ (DLIB) \math.1ib $(DLIB)\graphics.1lib 


You could then start make with the following command line: 


make DLIB=d:\lib 
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In this case, every occurrence of the macro “LIBS” would be expanded to 
the following: 


d:\lib\math.1lib d:\lib\graphics.lib 


Be careful to avoid infinitely recursive macros such as the following: 


QW > 
Hedi it 


6.2.6 Using Special Macros 


The make utility recognizes three special macro names and will automati- 
cally substitute a value for each. The special names and their values are 
described as follows: 


Name Value substituted 

}* Base-name portion of the target (without the extension) 
$@ Complete target name 

ales Complete list of dependencies 


These macro names can be used in description files, as shown in the follow- 
ing example: 


test.exe: modl.obj mod2.obj mod3.obj 
link $**, $@; 
mapsym $* 


The preceding example is equivalent to the following: 


test:exe: modl.obj mod2.obj mod3.obj 
link modl.obj mod2.obj mod3.obj, test.exe; 
mapsym test 


6.2.7 Inference Rules 


The make utility allows you to create inference rules that specify com- 
mands for target /dependent descriptions even when there is no explicit 
command in the make description file. An inference rule tells make how 
to produce a file with one type of extension from a file with the same base 
name and another type of extension. For example, if you define a rule for 
producing .o67 files from .asm files, the actual commands do not have to be 
repeated in the description file for each target /dependent description. 
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Inference rules take the following form: . 


.dependentextension.targetextenston : 
commandl 
[command] 


For lines that do not have explicit commands, make looks for a rule that 
matches both the target’s extension and the dependent’s extension. If it 
finds such a rule, make performs the commands given by the rule. 


The make utility looks first for dependency rules in the current descrip- 
tion file, but if it does not find an appropriate rule, it will search for the 
tools-initialization file, tools.ini, in the current drive and directory (or in 
any directories specified with the DOS path command). 


If make finds fools.inz, it looks through the file for a line beginning with 
the tag “|make]”. Inference rules following this line will be applied if 
appropriate. 


Example 


.asm.obj: 
masm S*.asm,,; 


testl.obj: testl.asm 


test2.obj: test2.asm 
masm test2.asm: 


In the preceding sample description file, an inference rule is defined in the 
first line. The filename in the rule is specified with the macro name $* so 
that the rule will apply to any base name. When make encounters the 
dependency for files test1.0bj7 and test1.asm, it looks first for commands on 
the next line. When it does not find any, make checks for a rule that may 
apply and finds the rule defined in the first lines of the description file. 
Then make applies the rule, replacing the $* macro with testi when it 
executes the following command: 


masm testl.asm,,:; 
When make reaches the second dependency for the ftesé2 files, it does not 


search for a dependency rule because a command is explicitly stated for 
this target /dependent description. 
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6.3 Maintaining a Program: an Example 


The make utility is especially useful for programs in development because 
it offers a quick way to re-create a modified program after small changes. 


Suppose you have a test program named fest.asm that you use to debug 
the routines in a library file named math.lib. The purpose of test.asm is to 
call one or more routines in the library so that you can make a study of 
their interaction. Each time test.asm is modified, it has to be assembled, a 
cross-reference listing has to be created, the assembled file has to be linked 
to the library, and finally a symbol file has to be created for use with the 
Microsoft Symbolic Debug Utility (symdeb). 


These tasks will be carried out when the following target /dependent 
descriptions are copied to the make description file test: 


test.obj: test.asm 
masm test,test,test, test 


test.ref: test.crf 
cref test,test 


test.exe: test.obj \lib\math.lib 
link4 test,test,test/map,\lib\math 


test.sym: test.map 
mapsym /l test.map 


These lines define the actions to be carried out to create four target files: 
test.obj, test.ref, test.exe, and test.sym. Each file has at least one dependent 
file and one command. The target /dependent descriptions are given in the 
order in which the target files will be created. Thus, test.sym depends on 
test.map, which is created by link4; test.exe depends on test.ob7, which is 
created by masm; and test.ref depends on test.crf, which also is created by 
masm. 


Once the description file is in place, you can create test.asm using a text 
editor, then invoke make to create all other required files. The command 
line should have the following form: 


make test 
The make utility carries out the following steps: 
1. It compares the modification date of test.asm with test.oby. If 


test.ob7 is out-of-date (or does not exist), make executes the follow- 
ing command: 


masm test,test,test,test 


Otherwise, it skips to the next target description. 
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2. It compares the dates of test.ref and test.crf. If test.refis out-of- 
date, make executes the following command: 


cref test,test 


3. It compares test.ere with the dates of test.obj and the library file 
math.lib. If test.exe is out-of-date with respect to either file, make 
executes the following command: 


link test,test,test/map,\lib\math.lib 


4. It compares the dates of test.sym and test.map. If test.sym 1s out- 
of-date, make executes the following command: 


mapsym /l1 test.map 


When test.asm is first created, make will execute all commands because 
none of the target files exist. If you invoke make again without changing 
any of the dependent files, it will skip all commands. If you change the 
library file math.lzb but make no other changes, make will execute the 
link4 command because test.exe is now out-of-date with respect to 
aaa It will also execute mapsym because test.map is created by 
link4. 
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7.1 Introduction 


This chapter describes the Cmacro macros, a set of assembly-language 
macros that can be used with the Microsoft Macro Assembler (MASM) to 
create assembly-language Windows applications. The Cmacros provide a 
simplified interface to the function and segment conventions of high-level 
languages, such as C and Pascal. 


The Cmacros are divided into the following groups: 


Segment macros 
Storage-allocation macros 
Function macros 

Call macros 
Special-definition macros 
Error macros 


The following sections describe each group in detail. 


7.2 CMACROS.INC File 


The file cmacros.inc contains the assembly-language definitions for all 
the Cmacro macros. You must include this file at the beginning of the 
assembly-language source file by using the INCLUDE directive. The line 
has the following form: 


INCLUDE cmacros.inc 


You must give the full pathname if the macro file is not in the current 
directory or in a directory specified on the command line. 


7.3 Cmacros Options 


The Cmacros provide assembly-time options that define the memory 
model and the calling conventions that the application will use. The 
options must be selected in the assembly-language source file prior to 
the INCLUDE directive. 
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7.3.1 Memory-Model Selection 


The memory-model options specify the memory model that the application 
will use. The memory model defines how many code and data segments are 
in the application. The following is a list of the possible memory models: 


Model Description 

Small One code segment and one data segment 

Medium Multiple code segments and one data segment 

Compact One code segment and multiple data segments 

Large Multiple code and data segments 

Huge Multiple code segments and multiple data seg- 
ae with one or more data items larger than 


You select a memory model by defining the option name at the beginning 
of the assembly-language source file. The following Table 7.1 shows the 
option names available: 


Table 7.1 
Memory Options 


Option Memory Code Data 
Name Model Size Size 


mems small small small 
memM medium large small 
memC compact small large 
memL large large large 
memH huge large large 


You can define a name by using the EQU directive. The definition has the 
following form: 


memM EQU nH 


If no option is selected, the default is model is small. 
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When you select a memory-model option, two symbols are defined. These 
two symbols can be used for code that is dependent on the memory model: 
SizeC O=small code 1 = large code 

sizeD O=smalldata l=largedata 2 = huge data 


7.3.2 Calling Conventions 


The calling-convention option specifies the high-level-language calling con- 
vention that the application will use. You can select the calling convention 
by defining the value of the symbol ?7PLM. The following Table 7.2 lists 
the values and conventions: 


Table 7.2 

Calling Conventions 

?PLM value Convention Description 

0 Standard C The caller pushes the rightmost 


argument onto the stack first, 
the leftmost last. The caller pops 
the arguments off the stack after 
control is returned. 


1 Pascal The caller pushes the leftmost 
argument onto the stack first, 
the rightmost last. The called 
function pops the arguments off 
the stack. 


You can set the PPLM symbol value by using the == directive. The state- 
ment has the following form: 


?PLM = 1 


The default is the Pascal convention. 


7.3.3 Windows Prolog/Epilog 


The Windows Prolog epilog option specifies whether or not special prolog 
and epilog code should be used with each function. This special code de- 
fines the current data segment for the given function and is required for 
Windows applications. 
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You select this option by defining the value of the symbol ?WIN. The fol- 
lowing Table 7.3 lists the values: 


Table 7.3 
Prolog /Epilog Code Options 


?WIN value Meaning 


Disables the special prolog/epilog code. 
1 Enables the special prolog/epilog code. 


You can set the PWIN symbol value by using the = directive. The state- 
ment has the following form: 


eWIN = 1 


The default is to have the prolog/epilog enabled. 


7.3.4 Stack-Checking Option 

You can enable stack checking by defining the symbol PCHKSTK. When 
stack checking is enabled, the prolog code calls the externally defined rou- 
tine CHKSTK to allocate local variables. 


You can define the PCHKSTK symbol by using the = directive. The 
statement has the following form: 


?CHKSTK = 1 
Once CHKSTK is defined, stack checking is enabled for the entire file. 
The default (when CHKSTK is not defined) is no stack checking. 


7.4 Segment Macros 


The segment macros give access to the code and data segments that an 
application will use. These segments have the names, attributes, classes, 
and groups required by Windows. 


The Cmacros have two predefined segments, named CODE and DATA, 
that any application can use without special definition. Medium-, large-, 
and huge-model applications can define additional segments by using the 
createSeg macro. 
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Syntax 
createSeg segName, logName, align, combine, class 


This macro creates a new segment that has the specified name and seg- 
ment attributes. The macro automatically creates an assumes macro and 
an OFFSET macro for the new segment. This macro is intended to be 
used in medium-model Windows applications to define non-resident seg- 
ments. The segName parameter specifies the actual name of the segment. 
This name 1s passed to the linker. 


The logName parameter specifies the logical name of the segment. This 
name 1s used in all subsequent sBegin, sEnd, and assumes macros that 
refer to the segment. 


The align parameter specifies the alignment type. It can be any one of the 
following: 


The combine parameter specifies the combine type for the segment. It can 
be any one of the following: 


PUBLIC 
STACK 
MEMORY 
COMMON 


If no combine type is given, a private segment is assumed. 

The class parameter specifies the class name of the segment. The class 
name defines which segments must be loaded in consecutive memory. 
Example 


createSeg _INIT, INITCODE , BYTE, PUBLIC, CODE 


sBegin INITCODE 
assumes CS: INITCODE 


mov ax,initcodeOFFSET sample 


sEnd INITCODE 
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Comments 


The alignment, combine type, and class name are described in detail in the 
Microsoft Macro Assembler Reference Manual. 


Syntax 
sBegin segName 


This macro opens up a segment. It is similar to the SEGMENT assem- 
bler directive. 


The segName parameter specifies the name of the segment to be opened. It 


can be one of the predefined segments, CODE or DATA, or the name of 
a, user-defined segment. 


Examples 
sBegin DATA 
sBegin CODE 
Syntax 

sEnd [segName] 


This macro closes a segment. It is similar to the ENDS assembler direc- 
tive. 


The optional segName parameter specifies a name used for readability. If it 
is given, it must be the same as the name given in the matching sBegin 
macro. 

Examples 

sEnd 

sEnd DATA 

Syntax 

assumes segheg, segName 

This macro makes all references to data and code in the segment 


segName relative to the segment register given by segfteg. It is similar 


to the ASSUME assembler directive. 
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The segReg parameter specifies the name of a segment register. 

The segName parameter specifies the name of a predefined segment, 
CODE or DATA, or a user-defined segment. 

Examples 


assumes CS, CODE 

assumes DS, CODE 

Syntax 

dataOFFSET arg 

This macro generates an offset relative to the start of the group to which 
the DATA segment belongs. It is similar to the OF FSET assembler 
operator, but automatically provides the group name. For this reason, 


it should be used instead of OF FSET. 


The arg parameter specifies a label name or offset value. 


Example 


mv ax,dataOFFSET label 


Syntax 

codeOF FSET arg 

This macro generates an offset relative to the start of the group to which 
the CODE segment belongs. It is similar to the OFFSET assembler 
operator, but automatically provides the group name. For this reason, 


it should be used instead of OFFSET. 


The arg parameter specifies a label name or offset value. 


Example 


mv ax,codeOFFSET label 
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Syntax 

segNameOFFSET arg 

This macro generates an offset relative to the start of the group to which 
the user-defined segment segName belongs. It is similar to the OFFSET 
assembler operator, but automatically provides the group name. For this 
reason, it should be used instead of OFFSET. 


The arg parameter specifies a label name or offset value. 


Example 


mv ax, initcodeOFFSET label 


7.4.1 Storage-Allocation Macros 

These macros allocate static memory (either private or public), declare 
externally defined memory and procedures, and allow the definition of 
public labels. 

Syntax 

staticX name, [initial Value], [replication] 

This macro allocates private static-memory storage. 


The X parameter specifies the size of storage to be allocated. It can be any 
one of the following: 


Type Description 


B Byte 

WwW Word 

D Double-word 

Q Quad-word 

T Ten bytes 

CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 


The name parameter specifies the reference name of the allocated memory. 
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The optional znztzal Value parameter specifies an initial value for the 
storage. If no value is specified, the default is zero. 


The optional replication parameter specifies a count of the number of 
times the allocation is to be duplicated. This parameter generates the 
DUP assembler operator. 

Examples 

staticW flag,1 

staticB string, , 30 

Syntax 

globalX name, [initial Value], | replication] 

This macro allocates public static-memory storage. 


The X parameter specifies the size of the storage to be allocated. It can be 
any one of the following: 


Type Description 


B Byte 

WwW Word 

D Double-word 

Q Quad-word 

T Ten bytes 

CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 


The name parameter specifies the reference name of the allocated memory. 


The optional inztzal Value parameter specifies an initial value for the 
storage. If no value is specified, the default is zero. 


The optional replication parameter specifies a count of the number of 
times the allocation is to be duplicated. This parameter generates the 
DUP assembler operator. 


Examples 


globalW flag,1l 
globalB string,O, 30 
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Syntax 
externX <namelist> 


This macro defines one or more names that will be the labels of external 
variables or functions. 


The X parameter specifies the storage size or function type. It can be any 
one of the following: | 


Type Description 


B Byte 

WwW Word 

D Double-word 

Q Quad-word 

T Ten bytes 

CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
NP Near function pointer 

FP Far function pointer 

P Near for small and compact models; far for other models 


The namelist parameter specifies the list of the names of the variables or 
functions. 

Examples 

externB <DataBase> 

externFP <SampleRead> 

Syntax 

labeLX <namelist> 


This macro defines one or more names that will be the labels of public 
(global) variables or functions. 


The X parameter specifies the storage size or function type. It can be any 
one of the following: 
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Type Description 


B Byte 

WwW Word 

D Double-word 

Q Quad-word 

T Ten bytes 

CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
NP Near function pointer 

FP Far function pointer 

5g Near for small and compact models; far for other models 


The namelist parameter specifies the list of the names of the external vari- 
ables or functions. 
Examples 


labelB <DataBase> 
labelFP <SampleRead> 


7.4.2 Function Macros 


The function macros define the names, attributes, parameters, and local 
variables of functions. 

Syntax 

cProc procName, <attributes>, <autoSave> 

This macro defines the name and attributes of a function. 

The procName parameter specifies the name of the function. 


The attributes parameter specifies the function type. It can be a combina- 
tion of the following: 
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Type Description 

NEAR A near function. It can only be called from the segment in 
which it is defined. 

FAR A far function. It can be called from any segment. 

PUBLIC A public function. It can be externally declared in other 
source files. 


The default attribute is NEAR and private (i.e., cannot be declared exter- 
nally in other source files). The NEAR and FAR attributes cannot be 
used together. If more than one attribute is selected, the angle brackets 
are required, 


The autoSave parameter specifies a list of registers to be saved when the 
function is invoked, and restored when exited. Any of the 8086’s registers 
can be specified. 


Comments 


The C calling conventions require that the si and di registers be saved 
before altering their contents. 


The bp register is always saved, regardless of whether it is present in the 
autoSave list. 
Examples 


cProc procl, <FAR, ds,es> 

cProc proc2, <NEAR,PUBLIC> 

cProc proc3,,ds 

Syntax 

parmX <namelist> 

This macro defines one or more function parameters. The parameters 
provide access to the arguments passed to the function. Parameters must 


appear in the same order as the arguments in the function call. 


The X parameter specifies the storage size. It can be any one of the follow- 
ing: 
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Type Description 


B Byte (allocated on a word boundary on the stack) 

WwW Word (allocated on a word boundary) 

D Double-word (allocated on a word boundary) 

Q Quad-word (aligned on a word boundary) 

T Ten-byte word (aligned on a word boundary) 

CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 


The namelist parameter specifies the list of the parameter names. 


Comments 

The parmD macro creates two additional symbols, OF F_. name 
and SEG_ name. OF F_ name is the offset portion of the parameter; 
SEG_ name is the segment portion. 


Only the parameter name is required when referring to the corresponding 
argument. Write your code like this: 


mov al,varl 


Not hke this: 


mov al,byte ptr varl [bp] 


Examples 


parmW varl 

parmB <var2,var3,var4> 

parmD <var5> 

Syntax 

locaLX <namelist>, size 

This macro defines one or more frame variables for the function. To keep 


the words in the stack aligned, the macro ensures that the total space allo- 
cated is an even number of bytes. 
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The X parameter specifies the storage size. It can be any one of the follow- 
ing: 


Type Description 


Byte (allocates a single byte of storage on the stack) —_ 
Word (allocated on a word boundary) 
Double-word (allocated on a word boundary) 
Variable size (allocated on a word boundary) 
Quad-word (aligned on a word boundary) 
Ten-byte word (aligned on a word boundary} 


Code pointer (one word for small and compact models) 


9 0 
UQue<udu 


Data pointer (one word for small and medium models) 


The namelist parameter specifies the list of the names of the frame vari- 
ables for the function. 


The size parameter specifies the size of the variable. It is used with localV 
only. 

Comments 

B-type variables are not necessarily aligned on word boundaries. 

The localD macro creates two additional symbols, OF F_ name 

and SEG_ name. OF F_ name is the offset portion of the parameter; 


SEG name is the segment portion. 


Only the name is required when referencing a variable. Write your code 
like this: 


mov al,varl 


Not like this: 


mov al,byte ptr varl [bp] 
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Examples 


localB <L1,L2,L3> 
localW L4 

localD <L5> 

localV L6,% (size struc) 


Syntax 


cBegin [procNamel 


This macro defines the actual entry point for the function procName. 
The macro creates code that sets up the frame and saves registers. 


The optional procName parameter specifies a function name. If it is given, 
it must be the same as the name given in the cProc macro immediately 
preceding the cBegin macro. 


Syntax 
cEnd [procName] 


This macro defines the exit point for the function procName. The macro 
creates code that discards the frame, restores registers, and returns to the 
caller. 


The optional procName parameter specifies a function name. If it is given, 
it must be the same as the name given in the cBegin macro immediately 
preceding the cEnd macro. 


Once a function has been defined using cProc, any formal parameters 
should be declared with the parm.X macro and any local variables with 
the locaLX macro. The cBegin and cEnd macros must be used to de- 
lineate the code for the function. 


The following is an example of a complete function definition: 
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Example 


cProc strepy, <PUBLIC>,<si,di> 
parmW dst 
parmW src 


localW cnt o~ 
cBegin 

cld 

mov si,sre 

mov di,dest 

push ds 

pop es 

xor Cx, Cx 

mov cnt, cx 
loop: 

lodsb 

stosb 

inc ent 

cmp al,O 

jnz loop 

mov ax,cnt 
cEnd 


7.4.3 Call Macros 


The call macros can be used to cal] cProc functions and high-level- 
language functions. These macros pass arguments according to the call- 
ing convention defined by the PPLM option. 


Syntax 


cCall procName, |< argList>], [<underscores>] 


This macro pushes the arguments in argList onto the stack, saves registers 
(if any), and calls the function procName. 


The procName parameter specifies the name of the function to be called. 
The optional argList parameter specifies a list of the names of arguments 
to be passed to the function. This list is not required if the Arg macro is 
used before cCall. 

The optional underscores parameter specifies whether or not an underscore 


should be added to the beginning of plaints If this argument is blank, 
an underscore is added. 
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Comments 


The arguments of an Arg macro are pushed onto the stack before any 
arguments in the argList parameter of a cCall macro. 


Byte-type parameters are passed as words. There is no sign extension or 
zeroing of the high-order byte. 


Immediate arguments are not supported. 


Examples 


cCall there, <pExt,ax,bx,pResult> 
Arg pExt 


Arg ax 
cCall there, <bx, pResult> 


Syntax 


Save <reglist> 


This macro directs the next cCall macro to save the specified registers 
on the stack before calling a function, and to restore the registers after 
the function returns. The macro can be used to save registers that are 
destroyed by the called function. 


The Save macro applies to one cCall macro only; each new cCall must 
have a corresponding Save macro. If two Save macros appear before a 
cCall, only the second macro is recognized. 


The regList parameter specifies a list of registers to be saved. 


Examples 

Save <cl,bh,si> 

pave <ax> 

Syntax 

Arg <namelist> 

This macro defines the arguments to be passed to a function by the next 


cCall macro. The arguments are pushed onto the stack in the order given. 
This order must correspond to the order of the function parameters. 
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More than one Arg macro can be given before each cCall. Multiple Arg 
macros have the same effect as a single macro. 


The namelist parameter specifies a list of argument names to be passed to 
the function. All names must have been previously defined. 
Comments 


Byte-type parameters are passed as words. There is no sign extension or 
zeroing of the high-order byte. 


Immediate arguments are not supported. 


Examples 

Arg varl 

Arg var2 

Arg var3 

Arg <varl,var2,var3> 


7.4.4 Special-Definition Macros 


The special-definition macros inform the Cmacros about user-defined 
variables, function-register use, and register pointers. 


Syntax 
Def X <namelist> 


This macro registers the name of a user-defined variable with the Cmac- 

ros. Variables that are not defined using the staticX, globaLX, extern, 

parm X, or locaLX macros cannot be referred to in other macros unless 

ae name is registered, or the variable was defined with the DW assembler 
irective. 


The X parameter specifies the storage size of the variable. It can be any 
one of the following: 


Type Description 


B Byte 

WwW Word 

D Double-word 
Q Quad-word 
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T Ten-byte word 
CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 


The namelist parameter specifies a list of variable names to be defined. 


Example 
maxSize db 132 
DefB maxSize 
dest equ wordptr es: [di] 


De fw dest 


Syntax 

FarPtr name, segment, offset 

This macro defines a 32-bit pointer value that can be passed as a single 
argument in a cCall macro. In the FarPtr macro, the segment and offset 
values do not have to be in registers. 


The name parameter specifies the name of the pointer to be created. 


The segment parameter specifies the text that defines the segment portion 
of the pointer. 


The offset parameter specifies the text that defines the offset portion of 
the pointer. 


Example 


FarPtr destPtr,es,<wordptr 3[si]> 
cCall proc, <destPtr,ax> 


7.4.5 Error Macros 


The error macros allow assertions to be coded into an assembly-language 
source program. [his lets you code optimum instruction sequences for 
some operations based on the variable allocation or bit position of flag 
in a word, and assert that the assumptions made are true. 


Error macros generate an error message to the console and an error mes- 


sage in the listing. Both the text that caused the error and the result of its 
evaluation are displayed in the generated error message. 
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Syntax 
errnz < expression > 


This macro evaluates a given expression. If the result is not zero, an error 
is displayed. 


The expression parameter specifies the expression to be evaluated. The 
angle brackets are required if there are any spaces in the expression. 


Examples 

x db ? 

Y db Fi 

mov ax, word ptr x 


errnz <(OFFSET y) - (OFFSET x) -1> 


If, during assembly, z and y receive anything but sequential storage loca- 
tions, errnz displays an error message. 


tablel struc 


tablellen equ $-tablel 
tablel ends 


table2 struc 


table2len equ $-table2 
table2 ends 


errnz tablelLen-table2Len 

If, during assembly, the length of two tables is not the same, errnz 
displays an error message. 

Syntax 

errn$ label, [bias] 

This macro subtracts the offset of label from the offset of the location 
counter, then adds dias to the result. If this result is not zero, then an 


error message is displayed. 


The label parameter specifies a label corresponding to a memory location. 
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The optional b:as parameter specifies a signed bias value. A plus or minus 
sign is required. 
Example 


: end of previous code 
errn$ functionl 
functionl: 


If a function that was me aoa located immediately after another piece of 
code is ever moved, errnd displays an error message. 


7.5 Using the Cmacros 


This section explains the assembly-language statements generated by some 
of the Cmacros and illustrates their use with an example of a Cmacros 
function called BITBLT. 

7.5.1 Overriding Types 


Parameters and local variables created using the parm_LX and locaLY mac- 
ros actually correspond to expressions of the following form: 


localB x ==> x equ byte ptr [bptnn] 
parmB y ==> y equ byte ptr [bptnn] 


In this example, the nn parameter specifies an offset from the current bp 
register value. 


These expressions let you use the names without having to explicitly type 
in “type ptr” and “[bp+offset]” operators. This means that “x” can be 
referred to as follows: 

mov al,x 

and that “y” can be referred to as follows: 


mov ax,y 


A problem arises if the type must be overridden. The assembler creates an 
error message if it encounters the following line: 


mov ax,word ptr x 
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This can be solved by enclosing the name in parentheses: 
mov ax,word ptr (x) 


One exception to this pattern is the localV macro. The expression gen- 
erated by this macro does not have a type associated with it. Therefore 
it can be overridden without the parentheses. For example: 


localV horse,10 ==> horse equ [bptnn] 


7.5.2 Symbol Redefinition 


Any symbol defined by a parm_X macro in one function can be redefined as 
a parameter in any other function. This allows different functions to refer 
to the same parameter by the same name, regardless of its location on the 
stack. 


7.5.3 Cmacros: a Sample Function 


The following example defines the assembly function BITBLT. BITBLT 
is a FAR and PUBLIC type function. When BITBLT 1s invoked, the si 
and di registers are automatically saved, and automatically restored upon 
exit. Note that the bp register is always saved. 


BITBLT is passed seven double-word pointers on the stack. Space will be 
allocated on the stack for eight frame variables (one structure, five bytes, 
and two words). | 


The cBegin macro defines the start of the actual code. The p#2zt parame- 
ter is loaded, and some values are loaded into registers. The ds and si 
registers are saved on the following cCall. 


Another C function, THERE, is invoked by the cCall macro. Four argu- 
ments are passed to THERE: pDestBitmap, the 32-bit pointer in ds:si, 
register ax, and register bx. The cCall macro places the arguments on the 
stack in the correct order. 


When THERE returns, the arguments placed on the stack are automati- 
cally removed, and the ds and si registers are restored. 


When cEnd is reached, the frame variables are removed, any autosave 


registers are restored, and a return of the correct type (near or far) is 
performed. 
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Example 


cProc BITBLT, <FAR, PUBLIC>,<si,di> 


parmD 
parmD 
parmD 
parmD 
parmD 
parmD 
parmD 


localV 


localB 
localB 
localB 


localW 
localW 


localB 
localB 


cBegin 


lds 
Mov 
mov 


RegPtr 
Save 


cCall 


mov 
mov 


cEnd 


pDestBitmap ;--> to dest bitmap descriptor 
pDestOrg ---> to dest origin (a point) 
pSrcBitmap :--> to source bitmap descriptor 
percOrg :--> to source origin 

pExt :--> to rectangle extent 

pRop ;--> to rasterop descriptor 
pBrush :--> to a physical brush 

nOps , 4 7# of each operand used 

phaseH :Horizontal phase (rotate count) 
PatRow ;Current row for patterns [0..7] 
direction sIncrement/decrement flag 
startMask smask for first dest byte 
lastMask smask for last dest byte 
firstFetch sNumber of first fetches needed 
stepDirection ;Direction of move (left, right) 
Si,pExt 


ax,extentX[si] 
bx, extentY [si] 


dest,ds,si 
<ds,si> 


THERE , <pDestBitmap, dest, ax,bx> 


extentxX [si] ,cx 
extentY [si] ,dx 
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8.1 Introduction 


You can create customized icons, cursors (pointers), and bitmaps for your 
applications by using the Microsoft Windows Icon Editor. Icon Editor lets 
you work on a large-scale icon, cursor, or bitmap while it displays the 
normal-scale replica of your work. 


Every application needs an icon to show that it is present, even if its win- 
dow 1s not open. Every application needs a cursor to show that the mouse 
is active when moved into the application’s window. Although Windows 
provides predefined icons and cursors, Icon Editor lets you create your own 
unique icons and cursors for your applications. 


The following sections explain how to use Icon Editor. 


Note 


Icon Editor must be used with a mouse or similar pointing device. 


8.2 Starting Icon Editor 


Icon Editor is a Windows application. To start it, open the MS-DOS Exec- 
utive window and double-click the filename zconedit.ere. Windows loads 
Icon Editor. 


Figure 8.1 shows the Icon Editor window: 
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Figure 8.1 Icon Editor Window 


The Icon Editor window has three main parts: the menu bar, which con- 
tains menu names; the display box; and the drawing box. 


The menu bar lists the menu names at the top of the window. You can 
select a menu by pointing to the name and clicking the left mouse button. 
Icon Editor has the following menus: 


File 
Edit 
Options 
Color 
Pensize 
Exit 


The display box is the box at the left of the screen. It contains the name of 
the current editing mode, information on resolution for editing and view- 
ing, and a normal-scale replica of your work. Initially, the drawing type is 
set to Icon. 


The drawing box is the large square box at the right of the screen. This 
box is the workspace where you will draw your icons, cursors, and bit- 
maps. The box is a magnified view of a small part of the screen. Each pixel 
in this box is many times larger than a pixel on the actual screen, so that 
you can see the individual pixels while doing your work. The box has an 
optional grid that you can use to help align pixels as you draw them. 
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8.3. Drawing in the Drawing Box 


To draw an icon or cursor, you simply move the mouse pointer into the 
drawing box and use the left and right mouse buttons to color and erase 
pixels: 


e Tocolor a pixel, point to the pixel and click the left mouse button. 
The pixel takes on the current pen color. 


e To color several pixels, use the left mouse button to drag the 
cursor over each pixel you want to color. The pixels take on the 
current pen color. 


e To erase a pixel, point to the pixel and click the right mouse 
button. The pixel takes on the current background color. 


e To erase several pixels, use the right mouse button to drag the 
cursor over each pixel you want to erase. The pixels take on the 
current background color. 


Pen size affects the way you color pixels. See Section 8.6 for information 
on the different pen sizes. 


Initially, the pen color is black and the background color is gray. You can 
change this by using the commands from the Color and Options menus, 
described in Sections 8.5 and 8.8, respectively. When you are drawing a 
bitmap, the pen color and background color work slightly differently than 
in the preceding list; see Section 8.4.3 for information on drawing bitmaps. 


You can draw straight lines by using the Options menu and selecting the 
Draw Straight command. 


8.4 Starting a New Drawing 


You can remove the current contents of the drawing box (and the display 
box) by using the New command. 


To clear the drawing box, choose the New command from the File menu. 
A new, empty file is opened and the drawing box and display box are 
cleared. The New Figure dialog box will appear. (If you made changes to 
the current file that you did not save, you will see a dialog box asking you 
whether you want to save them. If you want to save the changes, choose 
Yes; otherwise, choose No.) Figure 8.2 shows the New Figure dialog box: 
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Figure 8.2 The New Figure Dialog Box 


8.4.1 Choosing the Drawing Type 


Icon Editor has three modes or drawing types: Icon, for drawing and edit- 
ing icons; Cursor, for drawing and editing cursors; and Bitmap, for draw- 
ing and editing patterns. You can choose the drawing type by selecting it 
from the New Figure dialog box. 


To draw an icon, cursor, or bitmap, choose the Icon, Cursor, or Bitmap 
radio button from the dialog box. Icon Editor will change the label in the 
display box to reflect the new drawing type. It will also clear the drawing 
box and re-display the drawing grid. 


8.4.2 Choosing Resolution 


When you select the drawing type, you will also have the opportunity 

to select the resolution for editing and viewing Icons and Cursors. ‘The 
“lo-res” setting refers to CGA-compatible displays, the “med-res” setting 
corresponds to EGA-compatible displays, and “hi-res” is provided for 
displays that have a higher resolution than the EGA displays. You cannot 
select resolution unless you’re in device-dependent mode. When you’re not 
in device-dependent mode, the resolution is set at 64X 64 for icons and 
32X 32 for cursors. 


Icon Editor’s 64x 64-pixel display format for icons is based on a 

1024 1024-pixel display screen. If your screen has fewer pixels than this, 
Icon Editor will automatically adjust the full-scale image of your work 
(shown in the display box) to an image appropriate for your display- 
screen type. 
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For example, on 640 200-pixel monitors commonly used with the IBM 
PC, the 64X 64-pixel icon 1s reduced to a 32X 16-pixel block. Icon Editor 
simply deletes every other column and three of every four rows. As a 
result, the icon that appears in the display box 1s not necessarily an exact 
replica of your work. 


8.4.3 Working with Bitmaps 


When you select the Bitmap drawing type, Icon Editor changes the label 
on the display box to Bitmap. If appropriate, it also clears the drawing 
box and re-displays the drawing grid. 


You will need to specify a width and a height for the bitmap. The drawing 
box can be any size from 1X1 to 99X99 pixels. 


When you are drawing bitmaps, the background in the drawing box is set 
to white and cannot be affected by any choices from the Options menu; the 
pen color is set to black and cannot be affected by any choices from the 
Color menu. 


You can choose the Discardable checkbox to make your bitmap discard- 
able. This means that if the application needs more memory to run, it can 
discard the bitmap. Keep in mind that if the application does discard the 
bitmap, the bitmap will have to be loaded again if it’s needed again. 


8.4.4 Driver Dependence 


If you know precisely which display device the resource that you’re creat- 
ing is going to be used on, then choose the Device dependent checkbox. 
You can then choose the appropriate resolution, and you can be sure that 
the icon, cursor, or bitmap that you draw will look the same on the user’s 
screen as it looks in the display box now. However, since most Windows 
applications will be used on a variety of display devices, you will probably 
not want to limit yourself by choosing Device dependent. 


8.5 Changing the Pen Color 


You can change the color of the pen in Icon Editor by using the Color 
menu. The current pen color defines what color Icon Editor gives to an 
icon or cursor pixel when you color it by using the left mouse button. 


The Color menu lists four pen colors: White, Black, Screen, and Inverse 


Screen. An icon or cursor pixel with Screen color has the same color as the 
screen pixel underneath it. Inverse Screen is the inverted color; an icon or 
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cursor pixel with Inverse Screen color has the color that is the opposite of 
the screen color. For example, if the screen is white, the pixel is black; if 
the screen is light gray, the pixel is dark gray. 


For icons and cursors, you can use all four colors. For drawing bitmaps, 
the pen is set to black. 


To change the pen color, choose the desired color from the Color menu. 


8.6 Changing the Pen Size 


You can change the size of the pen by using the Pensize menu. The pen 
size determines the number of pixels you can color at once. The Pensize 
menu lists four pen sizes: Small, Medium, Large, and Extra Large. 


To change the pen size, choose the size you want from the Pensize menu. 


ee Small pen size works differently from the Medium, Large, and Extra 
arge. 


8.6.1 Small 


When you choose Small, the mouse pointer looks like a pencil when it’s in 
the drawing box. The left mouse button toggles between the pen color and 
its inverse color; the right mouse button toggles between the screen color 
and its inverse color. 


For instance, if the pen color is black and the screen color is light grey, 
this is what happens when you’re using the Small pen size: 


e Pointing to a pixel and clicking the left mouse button turns the 
pixel black. Clicking the same pixel again turns it white. 

e Pointing to a pixel and clicking the right mouse button turns the 
pixelight gray. Clicking the same pixel again turns it dark gray. 


Small is the default pen size. When you start Icon Editor, the pen size is 
set to Small. 


When you are drawing a bitmap, the left and right mouse buttons have 


the same effect in the Small pen size: either button will turn a black pixel 
white or a white pixel black. 
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8.6.2 Medium, Large, and Extra Large 


When you choose the Medium, Large, or Extra Large pen size, the pointer 
looks like a thin brush when it’s in the drawing box. The mouse buttons 
do not toggle. For example, if the pen color is set to black and the back- 
ground color is set to light gray, this is the effect when you’re using the 
Medium, Large, or Extra Large pen size: 


e Pointing to a pixel and clicking the left mouse button turns that 
pixel and the pixels around it black. Clicking the same pixel again 
has no effect. 


e Pointing to a pixel and clicking the right mouse button turns that 
pixel and the pixels around it light gray. Clicking the same pixel 
again has no effect. 


When you are drawing a bitmap, the left mouse button always colors the 
pixel black and the right mouse button always colors the pixel white. 


8.7 Setting the Hotspot 


In an icon, the hotspot is the pixel that Windows uses to determine where 
(column and row) to place a window that you have dragged into the work 
area. In a cursor, the hotspot is the pixel from which Windows will take 
the cursor’s current screen coordinates. To set the hotspot in an icon or 
cursor, follow these steps: 


1. Choose the Hotspot command from the Edit menu. A checkmark 
appears next to the command name. Information about the current 
location of the hotspot appears inside the display box. 


2. Move the mouse pointer to the location in the icon or cursor where 
you want to place the hotspot, and click the mouse button. The 
row and column information now indicates the location where you 
placed the hotspot. If you do not set the hotspot, Icon Editor 
places it by default in the center (row 16, column 16 for cursors; 
row 32, column 32 for icons). 


Only one hotspot per icon or cursor 1s allowed. You can change the hot- 
spot by dragging the pointer to a new location in the cursor or icon. 


If you want to continue drawing the icon or cursor after you have set the 
hotspot, you must again choose the Hotspot command from the Edit 
menu. When you do so, the checkmark next to Hotspot is removed and 
the row and column information disappears. 


187 


Microsoft Windows Programming Tools 


8.8 Changing the Background Color 


You can change the background color of the drawing box and the display 
box by using the Options menu. The Options menu lists four background 
colors: Black, White, Gray, and Light Gray. To change the background 
color, choose the desired color command from the Options menu. Icon Edi- 
tor re-displays the drawing box and display box with the new background. 


It is important to understand that the background color is used only for 
viewing. Changing the background color does not change what is stored in 
the icon, cursor, or bitmap file. Thus, you use the background color to see 
how an icon or cursor will look on a different background. For example, 
some icons may not look good on a gray background. By using the back- 
ground colors, you can test this before adding the icon to your application. 


When you open a new icon or cursor file, all the pixels in the file are 
Screen pixels. You create an icon or cursor by drawing pixels in the pen 
color. For icons and cursors, you have a choice of four pen colors: White, 
Black, Screen, and Inverse Screen. To see how these look on different back- 
grounds, you can choose any of the four background colors. 


Bitmaps, however, can have only white or black pixels. When you open a 
new bitmap, all the pixels are white. Since there cannot be any Screen or 
Inverse Screen pixels in bitmaps, the background color does not matter. 

The background color is shown only in the display box, outside the area 

of the bitmap itself; the background color is never part of the bitmap. 


8.9 Displaying the Drawing Grid 


The drawing grid is a grid of lines displayed in the drawing box to help 
you locate the individual pixels of an icon or cursor. 


To display the grid, choose the Grid command from the Options menu. 
To remove the grid, choose Grid again. 


8.10 Opening an Existing 
Icon, Cursor, or Bitmap File 


You can open an existing icon, cursor, or bitmap file by using the Open 
command in the File menu. Follow these steps: 
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1. Choose the Open command from the File menu. You will see the 
dialog box shown in Figure 8.3: 


Open File 
| Use mouse te choose file, or type filenane. | 


| Current directory...: C:\PUG 


Figure 8.3 Open File Dialog Box 


The list box displays files with the extension .tco, .cur, or .bmp, 
depending on whether Icon Editor is currently in Icon, Cursor, or 
Bitmap mode. 


2. Open the file using any of the following methods: 


e Double-click the filename in the list box. (If the file you want 
to open is in another directory or on another disk, double-click 
the directory name or the disk name. The filenames in that 
directory or on that disk that have the appropriate extension 
will be displayed in the list box, and you can then double-click 
the name of the file you want.) 


e Select the name in the list box, then choose the Open command 
or press the ENTER key. 


e Type the name in the text box, then choose the Open command 
or press the ENTER key. (If the file you want to open is in an- 
other directory or on another disk, type the full pathname in 
the text box.) 


If you want to view a listing of files of a different drawing type, use 
the wildcard character and the appropriate filename extension in 
the text box. For instance, to view the listing of bitmap files in the 
current directory, type +.bmp in the text box, then press ENTER. 


If you decide not to open a file, choose the Cancel button or press 
the ESCAPE key. 


Icon Editor opens the given file. If you have made changes to a file but 
haven’t saved them, Icon Editor displays a dialog box that asks whether 
you want to save the changes. 
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8.11 Saving Files 


You can save an icon, cursor, or bitmap in a file by using either the Save 
or the Save As command in the File menu. To save a file under the current 
filename, choose the Save command from the File menu. (If you attempt to 
save a file that doesn’t have a filename, you will see the Save As dialog 
box, described in the following paragraphs.) 


To save a file if there is no current filename, or if you want to save it 
under a new filename, follow these steps: 


1. Choose Save As from the File menu. You will see the dialog box 
shown in Figure 8.4: 


Save File 
Type filename to save figure as. 
Current directory..: C:\PUG 


Fi=Help 


Figure 8.4 Save As Dialog Box 


2. Type a valid filename in the text box. If you do not type an exten- 
sion, Icon Editor automatically supplies an extension based on the 
current drawing type: .zco for Icon, .cur for Cursor, and .bmp for 
Bitmap. 


3. Choose the Save button, or press the ENTER key. 


Icon Editor saves the icon, cursor, or bitmap in the named file. 


8.12 Using the Edit Menu 


You can cut selected areas, copy to the Clipboard, and paste from the 
Clipboard by using the commands in the Edit menu. 


If the Clipboard contains data, you can use the Paste command in the 
Edit menu to paste the material into the drawing box. This allows you to 
use drawings created with Microsoft Windows Paint, and other Windows 
applications. The area to be pasted in must be no larger than the current 
drawing area (in pixels). 
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You can also select areas of the current drawing and cut or copy them to 
the Clipboard. To select an area to cut or copy, you must choose either the 
Select or the Select All command. 


The Select command allows you to select an area of the current drawing. 
To select an area, do the following: 


1. Point to a corner of the area you want to select. 


2. Drag the mouse pointer diagonally to the opposite corner of the 
area you want to select, and release the mouse button. 


The Select All command selects the entire current drawing for cutting or 
copying to the Clipboard. 
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9.1 Introduction 


The Microsoft Windows Font Editor lets you create your own font files to 
use with your applications. A font file consists of a header, which contains 
information about the font, and a collection of character bitmaps that 
represent the individual letters, digits, and punctuation characters that 
can be used to display text on a display surface. This chapter describes 
how to use the Windows Font Editor to create fonts. 


Application writers who want to use fonts in their applications must add 
the new font files to a font resource file. For a description of how to make 
a font resource file, see the Microsoft Windows Programmer’s Reference. 


Note 


Font Editor can be used only to create and edit raster fonts. Vector 
font files are created as described in the Microsoft Windows Pro- 
grammer’s Reference. 


Font Editor must be used with a mouse or similar pointing device. 


9.2 Starting Font Editor 


Font Editor is a Windows application. To start it, open the MS-DOS Exec- 
utive window and double-click the filename fontedit.ere. Windows loads 
Font Editor. 


When you start Font Editor for the first time, it displays a dialog box, 
which lets you select the font file you want to edit. The dialog box is 
described in Section 9.3. 


9.3 Opening a Font File 


Font Editor does not allow you to create fonts from scratch. Instead, you 
open an existing font file, then make changes to it and, if you wish, save it 
under a new name as a new font. You can open a font file by using the 
Open command in the File menu. To do so, follow these steps: 
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1. Choose Open from the File menu. 


Font Editor displays a dialog box that contains a directory listing 
and a text box for entering a filename. 


2. Select the font file you want to open by using one of the following 
methods: 


e Double-click the filename in the list box. (If the file you want 
to open is in another directory or on another disk, double-click 
the directory name or the disk name. The filenames in that 
directory or on that disk that have the .fnf extension will be 
displayed in the list box, and you can then double-click the 
name of the file you want.) 


e Select the name in the list box, then choose the Open command 
or press the ENTER key. 


e Type the name in the test box, then choose the Open command 
or press the ENTER key. (If the file you want to open is in an- 
other directory or on another disk, type the full pathname in 
the text box.) 


Note 


Font Editor displays an error message if you try to load a file that 
does not contain a font. 


Once a font file is opened, you will see the font’s characters displayed in 
the font window and one of the characters displayed in the character 
window, as shown in Figure 9.1: 
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Character window Character-viewing window 


Char=65 
Width=28 
Height=18 
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Font window Main window 


Figure 9.1 Font Editor Window 


9.4 Font Editor Features 


Font Editor has the following features: 
Feature Description 


Main window This window contains Font Editor’s working 
windows. The menu bar contains the following 
menus: File, Edit, Font, Fill, Width, Row, and 
Column. 


Character window This window appears immediately below the 
menu bar and contains a copy of the character 
you want to edit. The window is divided by a grid 
into several rectangles. Each rectangle in the grid 
represents a single character pixel. You edit a 
character by turning these pixels on or off, or by 
adding or deleting pixels. 


Character-viewing This small window appears to the right of the 
window character window; it contains two normal-scale 
copies of the character in the character window. 
The character-viewing window lets you examine 
the effect of the changes you make to the charac- 
ter. It also lets you see the character’s leading 
the amount of vertical separation between lines). 
elow the character-viewing window is a list of 
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important information about the character, such 
as its ANSI value and its width and height in 
pixels. 


Font window This window appears at the bottom of the main 


window; it contains a font-viewing area and a 
scroll bar. The font-viewing area displays 
normal-scale copies of the characters in the font. 
The scroll bar lets you scroll the font-viewing 
area whenever there are more characters in the 
font than can fit. 


9.5 Selecting a Character to Edit 


You can select and edit any character in the currently loaded font. To 
select a character, follow these steps: 


1. Move the mouse pointer into the font-viewing area of the font 
window. 


2. Click the character you want to edit. 


Font Editor highlights your selection and copies it to the character 
window. 


Warning 


198 


When you make a new selection, Font Editor saves the old selection 
by copying it back to the font buffer. If you do not want to save the 
changes you’ve made to the old selection, make sure you cancel these 
changes, using the Refresh command in the Edit menu, before you 
make the new selection. See Section 9.7 for more information on the 
Refresh command. 


While you are editing a font, Font Editor keeps a copy of the font in 
memory. Changes to individual characters are saved in the buffer, but 
the font as a whole—including these changes—is not saved until you 
use the Save command or the Save As command to save it to the font 
file. See Section 9.23 for more information about saving a font. 
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9.6 Changing Pixels in a Character 


You can change the pixels j In a character by turning them off if they’re on, 
or on if they’re off. The “on” pixels make up the character shape or face 
and appear in the current text foreground color. The “off” pixels make up 
the character background and appear in the current background color. 
Changing the pixels changes the shape of the character. Use the mouse 
button to turn pixels on or off: 


e To turn a background pixel on, point to the pixel and click the 
mouse button. 


e To turn several background pixels on, point to a background pixel, 
then drag the mouse pointer over the pixels you want to change. 


e To turn a foreground pixel off, point to the pixel and click the 
mouse button. 


e To turn several foreground pixels off, point to a foreground pixel, 
then drag the mouse pointer over the pixels you want to change. 


9.7 Canceling Changes to a Character 


You can cancel all changes you have made to a character by using the 
Refresh command in the Edit menu. The command replaces the current 
character in the character window with a copy from the font window. 


Warning 


You cannot cancel changes to a character by selecting a new character. 
Selecting a new character, or even reselecting the current character, 
causes Windows to save all changes in the font buffer. Only the Refresh 
command cancels changes. 


If you have made changes you do not want, do not save the character. 
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9.8 Changing a Character’s Width 


You can change the width of a character belonging to a variable-pitch font 
by using the Width menu. The Width menu changes the number of col- 
umns in the character’s bitmap by letting you choose one of the following 
commands: 


Command Action 

Wider (left) Adds a blank column to the left side of the character. 

Wider (right) Adds a blank column to the right side of the 
character. 

Wider (both) Adds a blank column to each side of the character. 

Narrower (left) Deletes a column from the left side of the character. 


Narrower (right) Deletes a column from the right side of the character. 
Narrower (both) Deletes a column from each side of the character. 
To change a character’s width, choose the desired command from the 


Width menu. Font Editor changes the character window to show the new 
width. 


Note 
The width of a character can be changed only on variable-pitch fonts. 


Characters in a variable-pitch font cannot be wider than the maximum 
character width. If you try to make a character cell wider than the 
maximum character width, a dialog box will appear, warning you that 
the maximum character width will be increased. 


9.9 Copying a Row of Pixels 


You can make a copy of a whole or partial row of pixels by using the Add 
command in the Row menu. This command inserts a new row between the 
selected row and the row immediately below it. The pixels in the new row 
are turned on or off in the same pattern as in the selected row. 
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To copy a row, follow these steps: 


Choose Add from the Row menu. 


2. Move the mouse pointer to a pixel in the row you want to copy. 
To copy the entire row, point to the pixel at the far right. To copy 
a partial row, point to the right-most pixel you want to copy. 


3. Click the mouse button. 


When you copy a whole row, all rows below the selected row are pushed 
down one row, and the row at the bottom of the character window is 
pushed off the end. When you copy a partial row, only the selected pixel 
and the pixels to the left of the selected pixel are copied. The pixels in 
the rows below the copied pixels are pushed down as the new pixels are 
inserted, but the pixels to the right remain unchanged. 


9.10 Deleting a Row of Pixels 


You can delete a whole or partial row of pixels by using the Delete com- 
mand in the Row menu. This command deletes a selected row and causes 
rows below it to move up one row. 


To delete a row, follow these steps: 


1. Choose Delete from the Row menu. 


2. Move the mouse pointer to a pixel in the row you want to delete. 
To delete the entire row, point to the pixel at the far right. To 
delete a partial row, point to the right-most pixel you want to 
delete. 


3. Click the mouse button. 


When you delete a whole row, all rows below the selected row move up 
one row, and a blank row appears at the bottom of the character window. 
When you delete a partial row, only the selected pixel and the pixels to 
the left of the selected pixel are deleted. The pixels in the rows below the 
deleted pixels move up, but the pixels to the right remain unchanged. 


9.11 Copying a Column of Pixels 


You can make a copy of a whole or partial column of pixels by using the 
Add command in the Column menu. This command inserts a new column 
between the selected column and the column immediately to the right. 
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The pixels in the new column are turned on or off in the same pattern as 
those in the selected column. 


To copy a column, follow these steps: 


Choose Add from the Column menu. 


2. Move the mouse pointer to a pixel in the column you want to copy. 
To copy the entire column, point to the pixel at the bottom. To 
copy a partial column, point to the lowest pixel you want to copy. 


3. Click the mouse button. 


When you copy a whole column, all columns to the right of the selected 
column are pushed right one column, and the column at the far right of 
the character window is pushed off the side. When you copy a partial col- 
umn, only the selected pixel and the pixels above it are copied. The pixels 
in the columns to the right of the copied pixels are pushed right as the new 
pixels are inserted, but the pixels below remain unchanged. 


9.12 Deleting a Column of Pixels 


You can delete a whole or partial column of pixels by using the Delete 
command in the Column menu. This command deletes a selected column 
and causes columns below it to move one row to the left. 


To delete a column, follow these steps: 


1. Choose Delete from the Column menu. 


2. Move the mouse pointer to a pixel in the column you want to 
delete. To delete the entire column, point to the pixel at the bot- 
tom. To delete a partial column, point to the lowest pixel you 
want to delete. 


3. Click the mouse button. 


When you delete a whole column, all columns to the right of the selected 
column move left one column, and a blank column appears at the right 
side of the character window. When you delete a partial column, only the 
selected pixel and the pixels above it are deleted. The pixels in the col- 
umns to the right of the deleted pixels move left, but the pixels below 
remain unchanged. 
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9.13 Clearing the Character Window 


You can remove a block of foreground pixels from the character window 
by using the Clear command in the Fill menu. Follow these steps: 
1. Choose Clear from the Fill menu. 
Move the mouse pointer to a pixel in the character window. 


Press and hold down the mouse button. This creates an anchor 
point (displayed in gray) that represents a corner of the block you 
want to clear. 


4. Drag the pointer to another pixel. 

5. Release the mouse button. 
Font Editor uses the anchor point and the second pixel as diagonally oppo- 
site corners of the block you want to clear. All pixels within the block are 


cleared. If you drag the mouse pointer in a horizontal or vertical line, all 
pixels in the line are cleared. 


9.14 Filling the Character Window 
with a Solid Block 


You can fill the character window with a solid block of foreground pixels 
by using the Solid command in the Fill menu. Follow these steps: 

1. Choose Solid from the Fill menu. 

2. Move the mouse pointer to a pixel in the character window. 


3. Press and hold down the mouse button. This creates an anchor 
point (displayed in gray) that represents a corner of the block you 
want to fill. 


4. Drag the pointer to another pixel. 

5. Release the mouse button. 
Font Editor uses the anchor point and the second pixel as diagonally 
opposite corners of the block you want to fill. All pixels within the block 


become foreground pixels. If you drag the mouse pointer in a horizontal 
or vertical line, all pixels in the line become foreground pixels. 
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9.15 Filling the Character Window 
with a Hatched Pattern 


You can fill a block of the character window with a hatched pattern (alter- 
nate foreground and background) by using the Hatched command in the 
Fill menu. Follow these steps: 


Choose Hatched from the Fill menu. 


Move the mouse pointer to a pixel in the character window. 


Press and hold down the mouse button. This creates an anchor 
point (displayed in gray) that represents a corner of the block you 
want to fill. 


4. Drag the pointer to another pixel. 

5. Release the mouse button. 
Font Editor uses the anchor point and the second pixel as diagonally oppo- 
site corners of the block you want to fill. Every other pixel within the 
block becomes a foreground pixel, all others become background. If you 


drag the mouse pointer in a horizontal or vertical line, every other pixel in 
the line becomes a foreground pixel; all others become background pixels. 


9.16 Inverting the Character Window 


You can invert the pixels in a block in the character window by using 
the Inverted command in the Fill menu. (Foreground pixels become back- 
ground, background pixels become foreground.) Follow these steps: 


Choose Inverted from the Fill menu. 


2. Move the mouse pointer to a pixel in the character window. 


Press and hold down the mouse button. This creates an anchor 
point (displayed in gray) that represents a corner of the block you 
want to invert. 


4. Drag the pointer to another pixel. 

5. Release the mouse button. 
Font Editor uses the anchor point and the second pixel as diagonally oppo- 
site corners of the block you want to invert. All foreground pixels within 
the block become background pixels; all background pixels become fore- 


ground pixels. If you drag the mouse pointer in a horizontal or vertical 
line, the pixels in the line are inverted. 
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9.17 Reversing the Character Window 


You can reverse the pixels in a block in the character window by using the 
Left=Right or Top=Bottom commands in the Fill menu. The Left=Right 
command reverses the block by “flipping” the contents of a block along 

a vertical line in the center of the block. The Top=Bottom command 
reverses the block by flipping the contents of a block along a horizontal 
line in the center of the block. 


To reverse a block, follow these steps: 


Choose either Left=Right or Top=Bottom from the Fill menu. 
2. Move the mouse pointer to a pixel in the character window. 


3. Press and hold down the mouse button. This creates an anchor 
point (displayed in gray) that represents a corner of the block you 
want to reverse. 


4. Drag the pointer to another pixel. 
5. Release the mouse button. 
Font Editor uses the anchor point and the second pixel as diagonally 


opposite corners of the block you want to reverse. If you drag the mouse 
pointer in a horizontal or vertical line, the pixels in the line are reversed. 


9.18 Copying or Pasting 
in the Character Window 


You can copy a block of pixels to the Clipboard or fill a block with pixels 
from the Clipboard by using the Copy or Paste commands in the Fill 
menu. The Copy command copies the pixels in the block to the Clipboard. 
The Paste command fills the block with pixels from the Clipboard. 


To copy or paste a block, follow these steps: 


Choose Copy or Paste from the Fill menu. 
Move the mouse pointer to a pixel in the character window. 


Press and hold down the mouse button. This creates an anchor 
point (displayed in gray) that represents a corner of the block you 
want to copy or paste. 


4. Drag the pointer to another pixel. 


5. Release the mouse button. 
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Font Editor uses the anchor point and the second pixel as diagonally oppo- 
site corners of the block you want to copy or paste. If you drag the mouse 
pointer in a horizontal or vertical line, the pixels in the line are copied or 
pasted. 


Be sure that the area in the character window that you want to paste into 
is the same size as the block on the Clipboard that you want to paste. If 
you try to paste a block into an area that is larger or smaller than that 
block, Font Editor will try to stretch or squeeze the block to fit, and the 
results will be distorted. 


Note 


You can copy or paste the entire character window by using the Copy 
and Paste commands in the Edit menu. 


9.19 Undoing a Change 


You can recover from an editing mistake by using the Undo command in 
the Edit menu. This command restores the character window to what it 
was before the last change in the window. 


To recover from a mistake, choose the Undo command from the Edit 
menu. Font Editor restores the character window to its state before the 
last change. (If you chose Undo again, it returns the window to its changed 
state again.) 


The Undo command reverses changes made by the Fill, Row, Column, 
Width, Refresh, and Undo commands. It can also reverse changes made 
to individual pixels using the mouse. 


The Undo command cannot undo changes made to a character that has 
been saved in the buffer (that is, returned to the font). 


9.20 Saving Changes to a Character 


You can save the changes you have made to a character by following these 
steps: 
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1. Move the mouse pointer into the font-viewing area of the font 


window. 


2. Click the character you are currently editing (it is the highlighted 


character). 


Font Editor saves your selection by copying it back in the font. The font- 
viewing window is updated to show the new character. 


Note 


You can also save a character by making a new selection. Font Editor 
saves the old selection into the font buffer before copying the new 
selection to the character window. This is useful if you want to con- 
tinue editing characters in the same font. 


9.21 Resizing the Font 


You can change the height, width, and character mapping (ANSI value) 
of the font by using the Size command in the Font menu. The command 
displays a dialog box that contains the following options: 


Option 
Character Pixel 
Height 


Maximum Width 
eee 
onts only) 


Character Pixel 
Width (fixed-pitch 
fonts only) 


First Character 


Last Character 


Action 


Defines the height (in pixels) of the characters in 
the font. 


Defines the width (in pixels) of the widest possible 
character in the variable-pitch font. 


Defines the width (in pixels) of all characters in 
the fixed-pitch font. In fixed-pitch fonts, all char- 
acters have equal width. 


Defines the character value (for example, the 
ANSI value) of the first character in the font. 
The first character is the character to the far left 
when you scroll the contents of the font-viewing 
window all the way to the right. 


Defines the character value (for example, the 
ANSI value) of the last character in the font. 
The last character is the character to the far 
right when you scroll the contents of the font- 
viewing window all the way to the left. 
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Pitch Defines the kind of font. Fixed and Variable are 
mutually exclusive. If Fixed is selected, the font 
is fixed-pitch. If Variable is selected, the font is 
variable-pitch. 


Weight Lists options that define the font weight, ranging 
from thin to heavy. Each option represents the 
specific degree of heaviness (i.e., thickness of 
stroke) of the font. The options are mutually 
exclusive. 


Important 


You can change a font from fixed-pitch to variable-pitch by selecting 
Variable in the Size dialog box. You cannot change a variable-pitch 
font to fixed-pitch. 


To make a change to one of the height, width, first-character, or last- 
character options, follow these steps: 


1. Choose the Size command from the Font menu. Font Editor dis- 
plays the Size dialog box, which contains the size options. 


2. Select the contents of the text box for the option you want to 
change. The text box contains a number representing the current 
choice. 


3. Type anew number. 
4. Choose the OK button or press the ENTER key. 
Font Editor immediately makes the changes you have requested. Once 


the changes are complete, the new font is displayed in the font-viewing 
window. 


To change the pitch or weight of a font, follow these steps: 


1. Choose the appropriate radio button. 

2. Choose the OK button or press the ENTER key. 
When you change the width or height of a font, Font Editor stretches or 
compresses the existing characters to make new characters that have the 


given size. The resulting characters can then be corrected by hand, if 
necessary, to achieve the desired appearance. 
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9.22 Changing a Font File’s 
Header Information 


You can change the information in the font file’s header by using the 
Header command in the Font menu. The header contains everything about 
the font except the bitmap. The Header command displays a dialog box 
that contains a listing of the information in the header. The list consists 


of the following items: 


Item 


Face Name 


Kile Name 


Copyright 


Nominal Point Size 


Height of Ascent 


Nominal Vert. 
Resolution 


Nominal Horiz. 
Resolution 


External Leading 


Internal Leading 


Definition 


This character string is the name used to distin- 
guish the font from other fonts. It is not neces- 
sarily the same as the font filename. It can be up 
to 32 characters. 


This character string is the name of the font file 
being edited. 


This character string is either a copyright notice 
or additional information about the font. It can 
be up to 60 characters. 


This number defines the point size of the charac- 
ters in the font. One point is equal to approxi- 
mately 1/72 of an inch. 


This number defines the distance i pixels) from 
the top of an ascender to the baseline. 


This number defines the vertical resolution at 
which the characters were digitized. 


This number defines the horizontal resolution at 
which the characters were digitized. 


This number defines the pixel height of the font’s 
external leading. External leading is the vertical 
distance (in rows) from the bottom of one charac- 
ter cell to the top of the character cell below it. 
(The character-viewing window shows two copies 
of the character, one above the other, so that you 
can see the effect of leading.) 


This number defines the pixel height of the font’s 
internal leading. Internal leading is the vertical 
distance - rows) within a character cell above 
the top of the tallest letter; only marks such as 
accents, umlauts, and tildes for capital letters 
should appear within the space designated as 
internal leading. 
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Default Character 


Break Character 


ANSI or OEM 


Font Family 


Italic 
Underline 
Strikeout 
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This number defines the character value (for 
example, the ANSI value) of the default charac- 
ter. The default character is used whenever an 
attempt is made to display a character whose 
character value is less than that of the font’s 
first character or greater than that of the font’s 


- last character. 


This number defines the character value of the 
break character. The break character 1s used to 
pad lines that have been justified. The break 
character is typically the space character. tie 
example, in the ANSI character set, the value 
is 32. 


These options define the character set. The ANSI 
character set (value zero) is the default Windows 
character set. The OEM character set (value 255) 


is machine-specific. The number to the right of 
these options defines the character set. It can be 


any value from zero to 255, but only zero and 255 


have a predefined meaning. 


These options define the family to which the font 


belongs. Font families define the general charac- 
teristics of the font as follows: 


Family Name Description 


Roman Proportionally-spaced fonts 
with serifs (Times Roman, 


Century Schoolbook, Bodoni, 


etc.) 


Modern Fixed-pitch fonts (Pica, Elite, 


Courier, etc.) 


Swiss Proportionally-spaced fonts 
without serifs (Helvetica, 
Univers, Swiss, etc.) 


Decorative Novelty fonts 
Script Cursive or script fonts 
Dontcare Custom font 


This option defines an italic font. 
This option defines an underlined font. 


This option defines a font whose characters 
have been struck out. 
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To make a change to this information, follow these steps: 
1. Choose Header from the Font menu. Font Editor displays the 
Header dialog box, which contains the font options. 
2. Select the character string, number, or option you want to change. 
For character strings and numbers, type a new string or number. 
Choose the OK button or press the ENTER key. 


9.23 Saving a Font File 


You can save the changes you have made to a font by using the Save As 
command in the File menu. Follow these steps: 


1. Choose Save As from the File menu. Font Editor displays a dialog 
box that contains a text box where you can enter a filename. 


2. Enter the name of the file in which you want save the font. This 
can be a new file or an existing file. Use one of the following 
methods: 


e Enter the font filename by typing it in the text box of the 
dialog box. Choose the OK button or press the ENTER key. 


e Ifthe filename you want is shown in the text box, just choose 
the OK button or press the ENTER key. 


Once a font file is saved with your changes, you can continue editing the 
same font or load another font and edit it. 


While you are editing a font, Font Editor keeps a copy of the font in 


memory. No changes to the font file are made until you save the font by 
using the Save or Save As command. 


Note 


Use the .fnét filename extension for all font filenames. 
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9.24 Editing Tips 


When you are creating a new font, the closer the font you start working 
with is to the font you want to create, the better the results will be. For 
example, if you want the ANSI character set, make sure you start with an 
ANSI font. 


You cannot change a variable-pitch font to fixed-pitch, so if you want to 
create a fixed-pitch font, make sure you start with a fixed-pitch font. 


If you want to make several different sizes in the same kind of font, create 


the smallest font first. You get much better results making a small font 
larger than making a large font smaller. 
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10.1 Introduction 


The Microsoft Windows Dialog Editor lets you design a dialog box on 
the display screen and save a definition of the box in a resource file. The 
definition of the dialog box can be added to other resource definitions in 
your application’s resource script file. 


When you create a dialog box, you create the box outline, put controls 
and text for the controls in it, and define the way the user will use the 
controls. 


This chapter describes how to use Dialog Editor to create and modify dia- 
log boxes for your applications. It explains how to do the following: 


e Start the editor and create the outline of a dialog box 


e Add dialog controls, which the user will use to interact with the 
program 


e Set control styles and memory-manager flags 
e Define how a user can use the controls 

e Edit an existing dialog box 

e Create and modify the include file 


Note 


Dialog Editor must be used with a mouse or similar pointing device; 
some keystrokes can be used, however, and these will be noted. 


The Windows Dialog Editor creates dialog boxes. It does not edit other 
components of a resource file, such as strings, icons, and so forth. Before 
you use Dialog Editor, it is a good idea to create a .rc (resource script) file 
defining those components and to use the Windows resource compiler re 
to create a .res file (a binary version of the resource file). You can then use 
Dialog Editor to edit the .res file, adding dialog boxes. en you are fin- 
ished creating dialog boxes, use the # include directive in the .rc file to 
name the include file for the dialog boxes. Use the rcinclude keyword 

to name the .dig files. 


For more information about the resource script file, see Chapter 3, 


“Resource Compiler: Rc.” For more information about the .dl/g and 
.res files, see Section 10.10. 
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10.2 Starting Dialog Editor 


To start Dialog Editor, open the MS-DOS Executive window and double- 
click the filename dialog.exe. Windows loads Dialog Editor and displays 
the window shown in Figure 10.1: 


HFile Edit § 


Figure 10.1 Dialog Editor Window 


Dialog Editor’s menu bar contains the following menus: 
Menu Contents 


File Commands that create, open, and save the files that con- 
tain dialog boxes. There is also a command that allows you 
to view existing dialog boxes. 


Edit Commands that allow you to perform common editing 
functions such as cutting and pasting. There are also com- 
mands for creating a new dialog box, renaming an existing 
one, and defining the units by which the mouse moves. 


Styles Commands that allow you to control the styles, text, and 
ID values for the dialog-box controls. There is also a com- 
mand for defining memory management. 


Control Commands that let you define the type of controls to be 
placed in the dialog box. 


Include Commands that you use to create, modify, or view an 
include file. 


Options A command that allows you to define the order in which 
controls are accessed, and a command that allows you 
to test your dialog box. 
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10.3 Using the Size Window 


When you start Dialog Editor, you will notice a small window labeled 
“Size” in the lower-right corner of the screen. The Size window stays on 
your screen as you edit a dialog box and supplies you with information 
about the dialog box and the controls in it. When you make a change to 
the dialog box or controls, the change is reflected in the Size window. If 
necessary, the Size window can be moved out of the way of a dialog box 
you are working on. Figure 10.2 illustrates the Size window: 


$1ze 


Decimal Mode 


CHKBX2 


Figure 10.2 Size Window 


Control type 
Control ID value 


The Size window displays the information shown in the following list. All 
size/position values are in dialog units. (A dialog unit is a horizontal or 
vertical distance. One horizontal dialog unit is equal to 1/4 of the width of 
a character in the system font. One vertical dialog unit is equal to 1/8 of 
the height of a character in the system font.) 


Field Description 


xX Displays the position on the z-axis (vertical posi- 
tion) of the upper-left corner of the dialog box or 
control you have selected. 


y Displays the position on the yaxis (horizontal posi- 
tion) of the upper-left corner of the dialog box or 
control you have selected. 


CX Displays the height of the dialog box or control you 
have selected. 


cy Displays the width of the dialog box or control you 
have selected. 


Work/Test Mode Indicates whether Dialog Editor is in Work mode, 
in which you can edit the dialog box, or Test mode, 
in which you can try out the controls in the dialog 
box. 
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Decimal/Hex Mode Indicates whether the ID values for the controls are 
shown in decimal or hexadecimal numbers. 


Control Type Shows the type of control you have selected (for 
example, Radio Button or Check Box). If the dialog 
box was selected, this part of the Size window will _ 
read “Dialog.” 


Control ID Value Shows the ID value of the control you have selected. 
If the dialog box was selected, no ID value is shown. 


10.4 Creating a Dialog Box 


The first step in creating a dialog box is to create and size the outline of 
the box. 


10.4.1 Clearing the Display 


You should always clear Dialog Editor’s display before starting a new 
dialog box. To clear the display, choose the New command from the File 
menu. 


Dialog Editor clears the display, removing any existing dialog box. If you 
have previously made changes to the existing box, you will see a dialog box 


asking whether you want to save the changes. The New command opens a 
new file called sample, which is initially empty. 


10.4.2 Drawing the Border 


To create the border for a dialog box, use the Edit menu. Follow these 
steps: 
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Choose the New Dialog command from the Edit menu. You will be 
asked to enter a name for the new dialog box. 


Type a name for the box. 


Choose the OK button or press the ENTER key. This puts an empty 
dialog box on your screen. 


10.4.3. Expanding/Shrinking a Dialog Box 


To increase or decrease the size of the dialog box, use one of the eight 
“handles” (small, filled rectangles) on the boundaries, as shown in 
Figure 10.3: 


Handle for sizing 


Figure 10.3 Outline of a Dialog Box 


To change the size of a dialog box, follow these steps: 


1. 


Select the dialog box by clicking inside it. When a dialog box is 
selected, handles appear on its boundaries. 


Move the mouse pointer to a handle on the side you want to move. 
The pointer will change to a small box (similar to the handle.) 


Drag the border in the desired direction. When you release the 
mouse button, the dialog box will retain its new border. You can 
size the box in vertical and horizontal directions simultaneously 
by using a corner handle. 


10.5 Adding and Deleting Controls 


Controls in a dialog box allow the user to interact with the application. 
Once you have created the border for the dialog box, you can enter any 
number of the following controls: 
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Control 


Check box 


Radio button 


Push button 


Group box 


Horizontal scroll bar 


Vertical scroll bar 
List box 


Edit 


Text 


Frame 


Rectangle 


Icon 
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Action 


Creates a check box, a small square with a label 
to its right. Check boxes are independent of one 
another, although two or more often appear next 
to each other to give the user a choice of selec- 
tions. Any number of check boxes can be turned 
on or off at a given moment. 


Creates a radio button, a small circle with a label 
to its right. Radio buttons are typically used in 
groups to give the user a choice of selections. 
Only one radio button in a group can be selected 
at a time. 


Creates a push button, a small, rounded rectangle 
that contains a label. Push buttons are used to 
let the user choose an immediate action, such as 
canceling the dialog box. 


Creates a simple rectangle that has a label on its 
upper edge. Group boxes are used to enclose a 
collection or group of other controls, such as a 
group of radio buttons. 


Creates a horizontal scroll bar. Scroll bars let the 
user scroll data and are usually associated with 
another control or window that contains text or 
graphics. 


Creates a vertical scroll bar. 


Creates a simple rectangle that has a vertical 
scroll bar on its right edge. List boxes are used to 
display a list of strings, such as file or directory 
names. 


Creates an edit control, a rectangle in which the 
user can enter and edit text. Edit controls are 
used both to display numbers and text and to let 
the user type in numbers and text. 


Creates a static text control. Static text controls 
are used as labels for other controls, such as edit 
controls. 


Creates a rectangle that you can use to frame a 
control or group of controls. 


Creates a filled rectangle. 


Creates a rectangular space in which you can 
place an icon. (Do not size the icon space; icons 
automatically size themselves. ) 
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10.5.1 Adding Controls 


To add controls to a dialog box, use the Controls menu. Follow these 


steps: 


1. 


Select the control you want from the Controls menu. The mouse 
pointer changes to a plus sign (+). 


Position the pointer where you want to place the control. 


Click the mouse button. The control appears in the dialog box 
where you placed it. If it has text associated with it, the word 
“text” is included. To add text, see Section 10.5.2. 


10.5.2 Adding Text to Controls 


To add or change the text in a control, follow these steps: 


Select the control by clicking inside it. 


Choose Class Styles from the Styles menu. You will see a dialog 
box showing style information about the control. 


In the Window Text text box, type the text you want to have 
appear in the control. You can type more text than will fit in the 
text box. If you want to edit what you have typed, you can use the 
DIRECTION keys to move the insertion point, and then add text at 
the insertion point. To delete characters, use the BACKSPACE key. 


Choose the OK button or press the ENTER key to confirm your 
entry. (The Class Styles dialog box has other uses, which are 
described in Section 10.6.1.) 


Note 


When you add an Icon control to a dialog box, the text should be the 
name that was defined for the icon in the .rc file. For example, assume 
that the .rc file contains the following entry: 


myicon icon my.ico 


To use the icon in a dialog box, you would create an Icon control and 
type the name “myicon” in the Window Text section. 
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10.5.3. Moving a Control 


You can reposition a control in a dialog box either by using the mouse to 
drag it to a new location or by using the DIRECTION keys for fine adjust- 
ments. To move a control, follow these steps: 


1. Select the control. The mouse pointer changes to a plus sign (+). 


2. Drag the control to its new location. 


To move a control one dialog unit at a time, use the DIRECTION keys. In 
this way, you can move a control a few positions over (or up or down) 
without affecting its position on the other axis. This is helpful when you 
want to line up the controls. 


10.5.4 Moving a Group of Controls 


You can move a group of controls from one location in a dialog box to 
another. This can be useful if you decide to rearrange the layout of con- 
trols in the box and you have two or more controls that you want to keep 
together. To move a group of controls, follow these steps: 


Press and hold down the CONTROL key. 


2. While holding down the CONTROL key, select each control you want 
to keep in the group by using the mouse button. Each control will 
be outlined with a gray line; the group of controls will also have a 
gray border around it. (If you change your mind, you can reverse a 
selection by clicking it again with the mouse button. You must still 
be holding down the CONTROL key.) 


3. While still holding down the CONTROL key, point to a location 
inside the group border, but not inside any of the controls’ borders, 
as shown in Figure 10.4: 
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Figure 10.4 Pointer Position for Moving a Group of Controls 


4, Press and hold down the mouse button, then release the CONTROL 
key. 


5. Drag the group of controls to the desired location and release the 
mouse button. The group of controls is placed in the new location. 
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Note 


You must select all the controls you want to move, even if one control 
encloses another. For instance, to move several radio buttons and the 
group box that encloses them, you must select each radio button and 
the group box. 


10.5.5 Changing a Control’s Size 


To increase or decrease the size of a control, use one of the eight handles 
(small rectangles) on the boundaries. Follow these steps: 


1. Select the control. Handles appear on the boundaries of the 
control. 


2. Move the mouse pointer to a handle. The pointer changes to a 
small box, similar to the handle. 


3. Drag the border in the desired direction. When you release the 
mouse button, the control boundary retains the new size. 


10.5.6 Deleting Controls 


To delete a control from a dialog box, follow these steps: 


1. Select the control. 
2. Choose Clear Control from the Edit menu. The control is deleted. 


10.6 Changing Control Styles 
and Memory-Manager Flags 


The Styles menu allows you to set control styles and memory-manager 
flags. 


Control styles dictate such things as whether a control can be grayed, 

or whether a button is a default push button. You set the control styles 
available to a given class of controls by using the Class Styles command. 
Control styles that are available to all controls and to the dialog box itself 
are set using the Standard Styles command. 


Memory-manager flags determine whether a code segment is moveable, 
whether it is discardable, and whether it will be preloaded. 
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10.6.1 Changing Class Styles 


The Class Styles command in the Styles menu allows you to change the 
control styles that govern a control. You can also use this command to 
enter or change text in a control and to change the control’s ID value. 
ui an include file was loaded, you may symbolically refer to the control’s 
D value. For more information on include files, see Section 10.10.1.) 


To change a control style for a specific control, follow these steps: 


1. Select the control. 


2. Choose Class Styles from the Styles menu. You will see a dialog 
box that relates to the control you selected, similar to the dialog 
box shown in Figure 10.5: 
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Figure 10.5 Button Control Styles Dialog Box 


3. Select the desired options. Control-style options are described in 
Chapter 3, “Resource Compiler: Rc.” 


4. Choose the OK button or press the ENTER key. 


10.6.2 Changing Standard Styles 


The Standard Styles command in the Styles menu generates a dialog box 
that lists control styles that are available to all controls and to the dialog 
box itself. These are known as global window styles. You can use the Stan- 
dard Styles command to do such things as add a group marker or a tab 
stop for a control. 


224 


Dialog Editor 


To set global window styles, follow these steps: 


1. Select the appropriate control, or the dialog box itself. 


2. Choose Standard Styles from the Styles menu. The Standard Styles 
dialog box will appear, as shown in Figure 10.6: 


Global Vindow Styles 

[J Close Bax / Sys Menu Bax 

(J Horz Scroll Style C] Caption 

C} Vert Seroll Style C) Group Bit 

[] Dialog Frame J Tab Stop Bit 
[]$ize box [) Visible Bit 


Text bex for dialog 
Caption 


Figure 10.6 Standard Styles Dialog Box 


3. Turn on the check boxes for the styles you want to add (or turn 
off the ones for the styles you want to delete). 


. Add or delete text in the Window Text text box if desired. 
5. Choose the OK button or press the ENTER key. 


Note 


If the Visible Bit check box is turned on, the dialog box will be dis- 
played whenever it is called by the program. This may not be desirable 
in some cases. For example, if you have a command with an accelera- 
tor, you may not want to display a dialog box when the accelerator is 
used. You can prevent the display of a dialog box by leaving the Visi- 
ble Bit check box turned off. Generally, it is best to leave the Visible 
check box turned off unless you want the dialog box to be seen in 
all cases. 
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10.6.3 Including a System-Menu Box, 
a Size Box, or Scroll Bars 


You can include a system-menu (Control-menu) box, size box, or vertical 
or horizontal scroll bars as part of a dialog box. (These scroll-bar options 
are part of the dialog box; they are not separate controls. For more infor- 
mation on scroll-bar controls, scrolling functions, or window messages 
resulting from scrolling, see the Microsoft Windows Programmer’s Refer- 
ence.) For example, a mode-less dialog box must have a system menu so 
the user can close the box. 


To include a system-menu box, a size box, or scroll bars in a dialog box, 
follow these steps: 

1. Select the dialog box by clicking a blank area inside it. 

2. Choose Standard Styles from the Styles menu. 
3. Turn on the appropriate check box(es). 
4A 


Turn on the Border check box. (Each of these options requires that 
you turn on the Border check box. When you do so, the Caption 
check box is automatically turned on.) 


5. Choose the OK button or press the ENTER key to confirm your 
selections. 


10.6.4 Setting Memory-Manager Flags 


The Resource Properties command in the Styles menu allows you to set 
memory-manager flags for your dialog box. Memory-manager flags deter- 
mine how the code for a dialog box is treated by the application and by 
Windows with regard to memory. You can set options to specify when a 
resource is to be loaded into memory, as well as whether the resource is 
fixed or moveable and whether it is discardable. 


To set memory-manager flags, follow these steps: 


1. Select the dialog box you are working on. 


2. Choose the Resource Properties command from the Styles menu. 
You will see the dialog box shown in Figure 10.7: 
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Memory Manager Flags 
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Dialog Editor 


Figure 10.7 Resource Properties Dialog Box 


Turn on (or off) the check boxes corresponding to the memory- 
manager flags you want. (These options are described in Chapter 4, 
“Windows Linker: Link4.”) 


Choose the OK button or press the ENTER key. 


The way a dialog box reacts to the keyboard or mouse interface is based 
in part on the sequential order of the controls and the location of tab 
stops. You set these options by using the Order Groups command from 
the Options menu. Using this command, you can define the following: 


The sequential order of the controls. 


Which groups the controls are in and the sequential order of the 
groups. (A group is a collection of controls. Within a group of con- 
trols, the user makes selections using the DIRECTION keys.) 


The location of tab stops (the control that receives the input focus 
when the user presses the TAB key). 


When you choose the Order Groups command from the Options menu, you 
will see the Group/Control Ordering dialog box shown in Figure 10.8: 
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Figure 10.8 Group/Control Ordering Dialog Box 


10.7.1 Changing the Order of Controls 


By default, the controls you place in a dialog box receive the input focus 
(and thus are selected by the user) in the order in which they were placed 
in the box. For example, the first control you put in the box will receive 
the focus first, no matter where you subsequently move it in the dialog 
box. To change the sequential order, you must use the Order Groups com- 
mand and rearrange the controls in the list it displays. 


When you rearrange the order of the controls in the Group/Control 
Ordering dialog box, the control statements in the .dlg file are rearranged 
correspondingly. Thus, the first control listed in the .dlg file is the first to 
receive the input focus, the second listed is the second to receive the focus, 


and so on. 
To change the sequence of the controls in a dialog box, follow these steps: 
1. Choose Order Groups from the Options menu. You will see the 
dialog box shown in the preceding Figure 10.8. 
2. In the list box, select the control you want to move. 


3. Place the mouse pointer where you want the control to appear in 
the list box. Notice that as you move it, the pointer changes from 
an arrow to a short, horizontal bar. The bar appears only in places 
where you are allowed to insert the control. 


4. To insert the control, click the mouse button. 


Repeat steps 2 through 4 for any other controls you want to move. 
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Note 


If you decide to choose a different control to move, you can do so 
whenever the pointer appears as an arrow. Just point to the desired 
control and chick the mouse button. The new selection will replace 
the old. 


10.7.2 Setting a Tab Stop 


Tab stops determine where the pointer will move when the user presses 
the TAB key. Normally, tab stops are set for individual controls or, in the 
case of a group, for the first control in the group. To set a tab stop, follow 
these steps: 

1. Choose Order Groups from the Options menu. 


2. In the list box, select the control at which you want to place the 
tab stop. 


3. Select the Tab Stop button in the Group/Control Ordering dialog 
box. 


4. Choose the OK button. An asterisk appears next to the control, 
which indicates that a tab stop has been placed there. 


Note 


You can also set a tab stop by selecting the control, choosing Standard 
Styles from the Styles menu, and then turning on the Tab Stop Bit 
check box. 


10.7.3 Deleting a Tab Stop 


To delete a tab stop, follow these steps: 


1. Choose Order Groups from the Options menu. 


2. In the list box, select the control that has the tab stop. The Tab 
Stop button in the Group/Control Ordering dialog box will change 
to read “Delete Tab.” 


3. Select the Delete Tab button. The asterisk next to the selected 
control disappears. 


4. Choose the OK button or press the ENTER key. 
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Note 


You can also delete a tab stop by selecting the control, choosing Stan- 
dard Styles from the Styles menu, and turning off the Tab Stop Bit ye 
check box. a 


10.7.4 Adding a Group Marker 


To designate the beginning and end of a group, you add a “group marker” 
to the list of controls in the group. (The group marker appears in the list 
box of the Group/Control Ordering dialog box as a horizontal line of 
hyphens, as shown in the preceding Figure 10.8.) You need to place a 
group marker both before the first control and after the last control in 

a group. To add a group marker, follow these steps: 


Choose Order Groups from the Options menu. 


2. In the list box, select the control that appears just below where you 
want to place the group marker. 


3. Select the Group Marker button. The horizontal line indicates that 
the group marker has been inserted. 


. Repeat steps 2 and 3 until all markers have been placed. 
5. Choose the OK button. 


Note 


You can also add a group marker by using the Standard Styles com- 
mand from the Styles menu. Select the control, then turn on the Group 
Bit check box. A group marker will be placed just above the control 
you selected. 


10.7.5 Deleting a Group Marker 


To delete a group marker, follow these steps: 


1. Choose Order Groups from the Options menu. 


2. In the list box, select the group-marker line. The Group Marker 
button in the Group/Control Ordering dialog box will change to 
read “Delete Marker.” 
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3. Select the Delete Marker button. 
4. Choose the OK button. 


Note 


You can also delete a group marker by selecting the control, choosing 
Standard Styles from the Styles menu, and turning off the Group Bit 
check box. 


10.8 Modifying a Dialog Box 


To modify an existing dialog box, you open the .res file containing the 
dialog box, then use the procedures listed in this chapter to make the 
changes. To open the .res file and the dialog box for editing, follow these 
steps: 


1. Choose Open from the File menu. You will see a dialog box listing 
the available .res files in the current directory. The .res files con- 
tain the application’s dialog boxes. If the .res file you want is in 
eee directory, type the full pathname of the file in the text 

OX. 


2. Open the appropriate .res file. You will see a second dialog box, 
this one listing the available include files (.h extension). 


3. If you want to open an include file, do so. If not, choose the Cancel 
button. You will see a third dialog box, this one listing the dialog 
boxes in the .res file. 


4. Open the desired dialog box by double-clicking the name or by 
selecting the name and choosing the OK button. The dialog box 
you choose will appear on the screen and you can begin editing it. 


If you want to work on another dialog box in the same .res file, choose 


View Dialog from the File menu. You will again see the list of dialog-box 
hames you can choose from. 
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10.9 Using the Edit Menu 


The commands in the Edit menu will help you create or modify dialog 
boxes. The following list shows the command names and the result of 


each command: 
Command 


Restore Dialog 


Cut Dialog 


Copy Dialog 


Paste Dialog 


Clear Dialog /Control 


New Dialog 


Rename Dialog 


Grid 
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Result 


Allows you to restore the dialog box to its previ- 
ous saved state. 


Deletes the currently displayed dialog box and 
puts it on the Clipboard. (It cuts both the dialog 
format and the bitmap format, both of which can 
be edited with Paint.) 


Puts a copy of the currently displayed dialog box 
(both the dialog format and the bitmap format) 
on the Clipboard. 


Puts the contents of the Clipboard on the screen 
if the contents are in dialog format. 


Deletes the selected dialog box or control. If it 
is a dialog box, a confirmation message will be 
displayed. 


Puts the currently displayed dialog box back into 
the .res file and places a new, empty dialog box 
on the screen. Requests the name of the new dia- 
log box. 


Requests a new name for the dialog box currently 
displayed. 


Determines the location of the upper-left corner 
of a control. The grid is defined in multiples of 
dialog units. For example, when the grid is set 
at 20 horizontal (dx) units and 20 vertical (dy) 
units, the numbers defining the position of the 
control’s upper-left corner will be in multiples of 
20. Default settings are one dialog unit each in 
both horizontal and vertical directions. 


Dialog Editor 


10.10 Using Files with Dialog Editor 


The menus and strings that make up the user interface for a Windows 
application are generally defined in the resource script file, a text file that 
has the .rc extension. The application’s dialog boxes are defined in a text 
file that has the .dlg extension. These files are processed by re, the Win- 
dows resource compiler, producing a binary resource file that has the .res 
poe Ultimately, this .res file is linked to the application’s executable 
.exe file. 


When you use Dialog Editor, you modify the .res file that contains the 
binary form of the definitions for the dialog boxes. A typical use of Dialog 
Editor would be to open a .res file, create or modify dialog boxes, then 
save the results. Saving your results overwrites both the original .res file 
and any existing .dlg files. The new .res file contains the new dialog defini- 
tions, plus everything else that was included in the original .res file. This 
new .res file can be linked immediately to the application source file. The 
new .dig file is created as a backup in case you ever need to re-create the 
.res file using re. (For example, if you wanted to change or add to the 
menus and strings in the .rc file, you would have to do this manually, so 
the resource file would need to be recompiled.) The .dig file must be put 
into the .re file, either manually or by using the rcinclude keyword, before 
recompiling. 


One additional file, the include file, is associated with the dialog boxes 
that you created by using Dialog Editor. The include file is described in 
Section 10.10.1. 


10.10.1 Include File 


The include file contains control ID definitions (# define directives). These 
are used to define internal control numbers as symbolic constants. The 
symbolic constants can then be used in the application source code. For 
example, if a dialog box contains an OK push button, you can define the 
button ID as a constant, giving it a symbolic name such as CTLOK. Then 
you can use the symbolic name, CTLOK, in your application source code. 


When assigning [D values to controls, you can assign any numbers you 
want; however, there are some guidelines you should keep in mind. To 

use the ENTER and ESCAPE keys in standard ways, you need to create an 
include file and assign meaningful values to the corresponding controls. 
ID values 1 and 2 have special meanings. You should use these numbers as 
described in the following paragraphs so as not to confuse the user with 
controls that do not respond as expected. If you decide not to follow these 
guidelines, you should not use ID values of 1 and 2. 
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ID Value of 1 


When the ENTER, CANCEL, or ESCAPE key is pressed, Windows automati- 

cally sends a response message to the dialog-input function. If the dialog 

box has a default button (for example, the OK button), pressing the ENTER 

key sends a WM_.CO ND message, along with the ID value of 1. —_ 
Thus, if you have a default OK button, you should assign it an ID value 

of 1, so that it will be activated when the user presses the ENTER key. This 

is consistent with the recommended guidelines for creating a Windows 

application. (For information on application guidelines, see the Microsoft 

Windows Application Style Guide.) 


ID Value of 2 
When the CANCEL or ESCAPE key 1s pressed, Windows automatically sends 


a WM. COMMAND message, along with the ID value of 2. Thus, if you 
have a Cancel button in a dialog box, it should have an ID value of 2. 


10.10.2 Creating an Include File 


To create an include file, follow these steps: 
1. In the dialog box you are working on, select the control that you 
want to define in an include file. 


2. Choose View Include from the Include menu. You will see a dialog 
box similar to the one shown in Figure 10.9. 


Symbol name: |CHKBX1 
ID Value: [48 


Figure 10.9 View Include Dialog Box 


3. In the Symbol name text box, type the symbolic name you are giv- at 
ing to the control ID. 


4. In the ID Value text box, type the number you are assigning as the 
ID value. 
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5. Choose the Add button. 
6. Choose the OK button or press the ENTER key. 


7. Choose Save from the Include menu. 


10.10.3 Editing an Include File 


You can make changes to the symbols listed in an include file by using 

the View Include command from the Include menu. For example, you may 
want to change the name of a symbol or delete one of the symbols. To edit 
the include file, follow these steps: 


1. Choose View Include from the Include menu. You will see a dialog 
box, similar to the one in Figure 10.9, that lists the symbols in the 
file. 


Select the symbol you want to change or delete. 


To change a symbol’s name or ID value, make the change in the. 
appropriate text box, then select the Change button. To delete 
the symbol, select the Delete button. 


4. Choose the OK button or press the ENTER key. 


10.11 Saving a Dialog Box 


Once you have created a dialog box or made changes to it, save the new 
dialog box by choosing Save from the File menu. By default, the file will 
have the name sample.res. If you want to give it a different name, choose 
Save As and enter the new name in the resulting dialog box. 
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11.1 Introduction 


The Microsoft Windows Shaker and Heapwalker applications let you 
examine different aspects of system memory and see the effect your appli- 
cation has on them. This chapter explains how to use Shaker and Heap- 
walker. 


11.2 Testing Movable Memory: Shaker 


‘The Shaker application lets you see the effect of memory movement on 
your application. Shaker randomly allocates and frees chunks of global 
memory with the intention of forcing the system to move moveable data 
or code segments in your application. Shaker is useful for making sure that 
your application locks code and data segments properly when it tries to 
access them. 


To start Shaker, open the MS-DOS Executive window and double-click 
the filename shaker.exe. Windows loads the application and displays the 
Shaker window. 


Table 11.1 shows the Shaker commands: 


Table 11.1 


Shaker Commands 
Command Action 
Parameters Menu 


Allocation Granularity Sets the minimum size of the objects to be allocated. 
Each object is some multiple of this size; for example, if 
the granularity is 128, Shaker allocates objects that 
have byte sizes of 128, 256, 384, and so on. The smaller 
the granularity, the more likely it is that the allocated 
objects will fit in the spaces between global objects. 


Time Interval Sets the time interval, in system-timer ticks, between 
allocations. Shaker allocates a new object after each 
interval elapses. If the maximum number of objects has 
been allocated, it reallocates one it has already allocated. 
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Table 11.1 (continued) 


Command Action 


Max Objects Sets the maximum number of objects to be allocated. 


State Menu 

On Displays the object handles and the allocation sizes. 
Off Removes display of object handles and allocation sizes. 
Shake Menu 

Start Starts the allocation. 

Stop Stops the allocation. 

Step Allocates one object and stops. This command can be 


used when Shaker is otherwise stopped. 


Figure 11.1 shows the screen that is displayed when you choose the On 
command from the State menu: 
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Figure 11.1 Shaker Window with Show State On 
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11.3. Viewing the Global Heap: Heapwalker 


The Heapwalker application lets you examine the global heap. It displays 
es information about all objects in system memory and is useful for seeing 
what effect your application has when it allocates memory for its own use. 
To start Heapwalker, open the MS-DOS Executive window and double- 
click the filename heapwalk.exe. Windows loads the application and dis- 
plays the Heapwalker window. 


The global heap consists of all of available system memory. The heap 
contains global objects—areas of memory that have been allocated for 
some specific use. Some of these objects are free and can be allocated the 
next time an application calls the GlobalAlloc or GlobalRealloc func- 
tion. Some of the objects have already been allocated and contain data 
segments, code segments, resources, etc. 


Table 11.2 shows the Heapwalker commands: 


Table 11.2 

Heapwalker Commands 

Command Action 

Walk Menu 

Walk Heap Displays the current state of memory and 


identifies each object. Each display line 
identifies one global object. The display shows 
the following: 
e The segment address of the object 
(actually the segment of the arena 
eader; the object starts one 
paragraph later) 


The size of the object in bytes 
The lock count (for example, L2) 
Discardable flag, D 

The object’s owner 


The object type (code, data, resource, 
shared 
e Additional information for that object 


segment number or name for code, 
type of resource 


GC(0) and Walk Performs a global compact, asking for zero 
bytes, then displays the heap. 
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Table 11.2 (continued) 


Command 


GC(-1) and Walk 


GC(-1) and Hit A: 
Allocate all of memory 


Free allocated memory 


Free 2K of allocated memory 


Segmentation Test 


Sort Menu 


Address 
Module 

Size 

Label Segments 


Object Menu 


Show 


Show Bits 
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Action 


Allocates all of memory (causing all discardable 
objects to be thrown out), then displays the 
heap. 

Used for internal testing. 

Allocates all of free memory, which is useful for 
testing out-of-memory conditions in 
applications. 

Frees the memory allocated by the Allocate all 
of memory command. 

Frees z kilobytes of memory. This command 
applies only to memory allocated by the 
Allocate all of memory command. 

Dumps the heap to file hw6.r22 and does a 
global compact (—1). This command is available 


whenever Heapwalker is in the system, even if 
it is not the active application. 


Sorts the display by address. 
Sorts the display by module name. 
Sorts the display by allocation size. 


Directs Heapwalker to use .sym files in the 
current directory in order to substitute 
segment names for segment numbers. 


Displays the contents of the selected object in 
hexadecimal and ASCII. An object can be 
selected by clicking the object display. 


Displays the bitmap (if any) in the selected 
GDI object. An object can be selected by 
clicking the object display. 


Table 11.2 (continued) 


Command 


LocalWalk 


LC(-1) and LocalWalk 


GDI LocalWalk 


File Menu 


Save 


Exit 
About Heapwalker 


Shaker and Heapwalker 


Action 


Displays the objects in the currently selected 
local heap (data object). This display shows 
the following: | 


e The offset in the ds register of the 
object 


e The size in bytes of the object 
e Allocation status (Busy or Free) 
e The object type (Fixed or Movable) 


The first object in the local heap is allocated 
by the memory manager, so there are always at 
least two objects in a local heap. LocalWalk 
has a File menu with a Save command that 
saves to a file named hwl.rz, where the 
extension .rz is an incremental number 
appended by the program. 


Compacts the selected local heap, then 
displays the heap. LocalWalk has a File menu 
with a Save command that saves to a file 
named hwl.xz, where the extension .zz is an 
incremental number appended by the program. 


Does a local walk of the GDI local heap and 
provides expanded information on the objects 
in the heap. LocalWalk has a File menu with a 
Save command that saves to a file named 
hwl.az, where the extension .zz is an 
incremental number appended by the program. 


Displays the global heap and writes the results 
to a file named hwg.xzxz. The extension .rz is an 


incremental number appended by the program. 


Quits the Heapwalker application. 


Displays information about the current version 
of Heapwalker. 
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Figure 11.2 shows the screen that is displayed when you choose the Walk 
Heap command from the Walk menu: 
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KERNEL 
InitTask 


KEYBOARD 
KEYBOARD 
KEYBOARD 
HOUSE 
MOUSE 
MOUSE 
DISPLAY 
DISPLAY 
DISPLAY 
SOUND 


SOUND — 


CODE 
TASK 
DATA 
SHARED 
DATABASE 


CODE 
DATABASE 
DATA 


CODE 
DATABASE 
DATA 
CODE 
DATABASE 
DATA 
CODE 
DATABASE 
CODE 


Figure 11.2 Heapwalker Window after Walk Command 
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Appendix A 


Diagnostic Messages 


The debugging version of Microsoft Windows generates diagnostic mes- 
sages whenever it encounters an error that would otherwise cause the sys- 
tem to fail. Each diagnostic message has a unique number that identifies 
the cause of the message and potential failure. Table A.1 lists most of the 
diagnostic message numbers and explains the meaning of each message. 


Table A.1 


Diagnostic Messages 


Number (Hex) 


Description 


Insufficient memory for allocation 
Error reallocating memory 
Memory cannot be freed 

Memory cannot be locked 
Memory cannot be unlocked 
Window handle not valid 

Cached display contexts are busy 
Clipboard already open 

Mouse module not valid 

Display module not valid 
Unlocked data segment should be locked 
Invalid lock on system queue 
Local memory errors 

Local heap is busy 

Invalid local handle 

LocalLock count overflow 
LocalUnlock count underflow 
Global memory errors 

Critical section problems 

Invalid global handle 
GlobalLock count overflow 
GlobalUnlock count underflow 
Task schedule errors 

Invalid task ID 

Invalid exit system call 

Invalid bp register chain 
Dynamic loader /linker errors 
Error during boot process 
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Table A.1 (continued) 


Number (Hex) Description 


0402 Error loading a module 

0403 Invalid ordinal reference 

0404 Invalid entry name reference 

0405 Invalid start procedure 

0406 Invalid module handle 

0407 Invalid relocation record 

0408 Error saving forward reference 

0409 Error reading segment contents 

0410 Error reading segment contents 

0411 Insert disk for specified file 

0412 Error reading non-resident table 
O4FF INT 3F handler unable to load segment 
0500 Resource manager/user profile errors 
0501 Missing resource table 

0502 Bad resource type 

0503 Bad resource name 

0504 Bad resource file 

0505 Error reading resource 

0600 Atom manager errors 

0700 Input /output package errors 
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Appendix B 
C Run-time Functions 


Table B.1 lists all C run-time functions and indicates whether the func- 
tion code assumes that the ds and ss registers are equal. Only C run-time 
functions that assume that ds and ss are not equal can be used in Win- 
dows libraries. 


Table B.1 

C Run-time Functions 

Function ds!=ss Function ds !=ss 
_ clear87 yes bessel yes 
—control87 yes bsearch yes 
_ exit no cabs yes 
_ expand yes calloc yes 
_. ffree yes ceil yes 
—fmalloc yes cegets yes 
_fmsize yes chdir yes 
— fpreset yes chmod yes 
_ freect yes chsize no 
— memav]l yes clearerr yes 
_msize yes close yes 
_nfree yes cos yes 
—nmalloce yes cosh yes 
__ nmsize yes eprintf no 
— status87 yes cputs yes 
abort no creat no 
abs yes escanf no 
access yes ctime yes 
acos yes dieeetomsbin _yes 
alloca yes difftime yes 
asctime yes dmsbintoiees _syes 
asin yes dosexterr yes 
atan yes dup yes 
atan2 yes dup2 yes 
atof yes ecvt yes 
atoi yes eof yes 
atol yes execl no 
bdos yes execle no 
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Table B.1 (continued) 
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Function ds!=ss Function ds !==ss 
execlp no getw yes 
execlpe no gmtime yes 
execy no halloc yes 
execve no hfree yes 
execvp no hypot yes 
execvpe no inp yes 
exit no int86 yes 
exp yes int86x yes 
fabs yes intdos yes 
fclose yes intdosx yes 
fcloseall yes isatty yes 
fevt yes itoa yes 
fdopen yes kbhit yes 
fgetc yes labs yes 
fgetchar yes Idexp yes 
fgets yes lfind yes 
fieeetomsbin yes localtime yes 
filelength yes locking yes 
flush yes log yes 
floor yes log10 yes 
flushall yes longjmp yes 
fmod yes Isearch yes 
fmsbintoieee yes Iseek yes 
fopen yes ltoa yes 
fprintf no malloc yes 
fpute yes matherr yes 
fputchar yes memccpy yes 
fputs yes memchr yes 
fread yes memcmp yes 
free yes memcpy yes 
freopen yes memicmp yes 
frexp yes memset yes 
fscanf no mkdir yes 
fseek yes mktemp yes 
fstat yes modf yes 
ftell yes movedata yes 
ftime yes onexit yes 
fwrite yes open yes 
gevt yes outp yes 
getch yes perror yes 
getche yes pow yes 
getewd yes printf no 
getenv yes putch yes 
getpid yes putenv yes 
gets yes puts yes 


Table B.1 (continued) 


Function 


putw 
qsort 
rand 
read 
realloc 
remove 
rename 
rmdir 
rmtmp 
sbrk 
scanf 
segread 
setbuf 
setjmp 
setmode 
setvbuf 
signal 
sin 

sinh 
sopen 
spawnl 
spawnle 
spawnlp 
spawnlpe 
spawnv 
spawnve 
spawnvp 
spawnvpe 
sprintf 
sqrt 
srand 
sscanf 
stackavail 
stat 
strcat 
strcehr 
strcmp 
strempi 
strcepy 
strcespn 
strdup 


ds !==ss 


yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
no 

yes 
yes 
yes 
yes 


Function 


strerror 
stricmp 
strlen 
strlwr 
strncat 
strncemp 
strncpy 
strnicmp 
strnset 
strpbrk 
strrchr 
strrev 
strset 
strspn 
strstr 
strtod 
strtok 
strtol 
strupr 
swab 
system 


toupper 
tzset 
ultoa 
umask 
ungetc 
ungetch 
unlink 
utime 
vfprintf 
vprintf 
vsprintf 
write 


ds !=ss 


yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
no 

yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
no 

no 

no 


yes 


C Run-time Functions 
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Index 


& (ampersand) 
ialog-control statement, use in 
47-51, 53-55 
MENUITEM statement, use in, 38 
* (asterisk) 
argument (symdeb), 104 
command, 112, 138 
parameter (x? command), 135 
wildcard character, 106, 135 
= command, 99, 101, 112, 137, 155-156 
! command, 112, 137 
* command, 112, 138 
< command, 112, 137 
> command, 112, 137 
{ command, 112, 137 
} command, 112, 137 
command, 112, 137 
. (dot) command, 112, 136 
= \Ay pen); symdeb option designator, 


(@ aa 101, 131 
(question mark) 
command, 112, 136 
arameter (x? command), 135 
/ (slash), te option designator, 
101- 102 
$x, special macro name, 147 
$ xx, special macro name, 147 
$@, special macro name, 147 


a (assemble) command, 110, 118 
/a (escape character), 38 
About Heapwalker command, 243 
~AC option, 12 
Accelerator, 35 
See also ACCELERATORS 
ACCELERATORS 
acctablename field, 35, 36 
resource, 35 
resource statement, 25, 35, 36 
——acrtused symbol, 22 
Add command, 200-201 
Add hexadecimal (h command), 111, 
129 
Address argument (symdeb), 116-119 


Address command argument (symdeb), 


113 
Address command (Heapwalker)}, 242 


Address parameter 
a command, 118 
ba command, 119 
bp command, 121 
c command, 121 
e command, 125 
ea command, 126 
eb command, 126 
ed command, 126 
el command, 127 
es command, 127 
et command, 127 
ew command, 128 
1 command, 130 
m command, 130 
w command, 134 
—AL option, 12 
Align parameter, createSeg macro 
(Cmacro), 157 
/alignment option, 86 
Allocate all of memory command 
Eeepwalker)) 242 
Allocation granularity command 
(Shaker), 239 
Allocation message, 107 
Allocation status, system memory, 243 
—-AM option, 12 
Ampersand (&) See & (ampersand) 
—An option, 19 
Anchor point, 203-205 
ANSI character set, 210 
Application 
allocating memory, 241 
assembling, 11 
assembly-language, 20 
C-language, 11 
code size, 15 
compiling, 11, 14 
creating, 11 
debugging, 95 
development language, 11 
development tools, 3 
Dialog Editor, 215 
entry point, 13 
executable See Linking 
Font Editor, 195 
Heapwalker, 239, 241 
import library, 88 
library, 16 
linking, 73, 85 
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Application (continued) 
memory-movement, 239 
model, 12 
module-definition file, 73 
module name, 73 
Pascal calling convention, 13 
Pascal language, 20 
program, 11 
programming model, 12-13, 16 
recommendation, 74 
requirement, 74 
resource, 11, 25 
resource need, 181 
resource script file, 215 
Shaker, 239 
source code, 233 
source file, 11 
starting, 107 
symbol file, 102 
Windows library, 19-20 
WinMain function, 13 
Arg, 169 
Arg parameter (Cmacro) 
codeOFFSET macro, 159 
dataOFFSET macro, 159 
segNameOFFSET macro, 160 
.... argc variable, 16 
Argument 
symdeb address, 116-117 
symdeb command, 113-115, 116-117 
symdeb expression, 117 
Arguments parameter 
n command, 131 
symdeb command, 100 
_ — argv variable, 16 
—As option, 19 
—AS option, 12, 19 
Assemble (2 command), 110, 118 
Assembly language, 11 
application, 20 
Cmacro, 153 
routine, 17 
symbol file, 98 
assumes macro (Cmacro), 157, 158-159 
Attributes parameter, cProc macro 
(Cmacro), 163 
Autosave parameter, cProc macro 
(Cmacro), 164 
—Aw option, 19 


ba on address) command, 110, 
119 

Background color (Icon Editor), 188 

Backtrace stack (k seer 111, 129 


Backtrace task (kt command 111, 
129-130 
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Batch-processing program, 141 

be (breakpoint clear) command 
110, 120, 121 

bd (breakpoint disable) command, 111, 
120, 121 

be (breakpoint enable) command, 111, 
120 


Bias parameter, errn$ macro (Cmacro), 


Binary operator (symdeb), 117 
Binary resource file (Dialog Editor), 233 
BITBLT (Cmacro), 173 
Bitmap 
background color, 188 
creating, 181 
opening existing file, 188 
opening new file, 183-184 
saving file, 190 
BITMAP 
keyword, 30 
resource, 30 
resource statement, 25, 30 
bl (breakpoint list) command, 111, 121 
Border, 44 
Border check box, 226 
bp (breakpoint set) command, 108, 
111, 121 


Brackets 
double ({ |), 4 
single ({ |), 105 


Breakaddress parameter (g command), 


Breakpoint address (ba) command, 
110, 119 
Breakpoint clear (bc) command, 110, 


Breakpoint disable (bd) command, 111, 
Breakpoint enable (be) command, 111, 


Breakpoint list (bl) command, 111, 121 
Breakpoint set p) command, 108, 
111, 121 
Breakpoint 
interrupt key, 108 
setting, 108 
sticky, 121 
virtual setting, 108 
BS_ 3STATE, 61 
BS_ AUTO8STATE, 61 
BS_ AUTOCHECKBOX, 60 
BS. AUTORADIOBUTTON, 61 
BS_. CHECKBOX, 60, 61 
BS. DEFPUSHBUTTON, 60 
BS_ GROUPBOX, 60 
BS_ LEFTTEXT, 61 


BS_ PUSHBUTTON, 60 
BS. RADIOBUTTON, 61 
BS. USERBUTTON, 61 
BUTTON control 
checkbox, 50 
class, 59 
style, 51-52, 54-56, 60-61 
Byte command argument (symdeb), 
113 


Byte parameter (o command), 131 
Bytes field 
HEAPSIZE statement, 77 
STACKSIZE statement, 78 


¢ (compare) command, 111, 121 
C compiler, 11 
default option, 15 
option, 14 | 
C language, 11 
application, 11 
debugging, 95 
library, 16, 19, 22 
Pascal calling convention, 13 
program, debugging, 95 
run-time function, 17, 19-20, 249-251 
run-time library, 16, 17, 22 
symbol file, 97 
—c option, 14 
Call macro (Cmacro), 168 
Callback function, 13, 19, 21 
Calling convention 
cmacro, 155 
high-level language, 21 
Pascal, 13, 21 
calloc function, 17 
Cancel button (Dialog Editor), 231, 234 
Cancel command (symdeb 
See CONTROL+C key 
CANCEL key, assigning ID value, 234 
Caption check box, 226 
CAPTION statement, 43, 45 
Captiontext field aren 
statement), 4 
cBegin (Cmacro), 167 
cCall (Cmacro), 168 
Arg, use of, 169 
FarPtr, use of, 171 
Save, use of, 169 
cEnd (Cmacro), 167 
Change button (Dialog Editor), 235 
Character 
See also Font Editor 
escape, 38 
variable-pitch font, width restriction, 


Index 


Character set, 210 
Character window 
clearing, 203 
Font Editor, 197 
Character-viewing window (Font 
Editor), 197 
Check box 
Border, 226 
Caption, 226 
description, 220 
dialog-box control, 220 
Group Bit, 230 
Tab Stop Bit, 229-231 
Visible Bit, 225 
CHECKBOX statement, 47, 50-51 
CHECKED option 
MENUITEM statement, 38 
POPUP statement, 39 
Child window, clipping, 43, 45 
?CHKSTK (Cmacro), 156 
cl command, 3, 11, 14 
Class field 
CLASS statement, 46 
CONTROL statement, 58 
Class-name field (SEGMENTS 
statement), 81 
Class parameter, createSeg macro 
(Cmacro), 157 
CLASS statement, 43, 46 
Class style, 223-224 
See also Resource compiler 
Class Styles command 
dialog box, 223 
dialog-box control, 223 
Dialog Editor, 221, 224 
Clear breakpoint command 
See bc command 
Clear command (Font ee 203 
Clear Control command (Dialog 
Editor), 223 
Clear Dialog/Control command (Dialog 
Editor), 232 
Chipboard, 205 
Clipping, child window, 43, 45 
Close command, 110 
Cmacro 
Arg, 169, 170 
assumes, 157, 158-159 
BITBLT, 173 
call, 168 
calling convention, 155 
calling cProc function, 168 
calling high-level language function, 
168 


cBegin, 167 
cCall, 168 
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Cmacro (continued) 
cEnd, 167 
codeOF FSET, 159 
cProc, 163, 164 
createSeg, 156, 157 
dataOF FSET, 159 
defined, 153 
DefX, 170, 171 
described, 3 
errn$, 172, 173 
errnz, 172 
Error, 171 
example, 173-174 
externX, 162 
FarPtr, 171 
function, 163 
globalX, 161 
INCLUDE command, 153 
include file, 215, 231, 133-235 
labelX, 162, 163 
localX, 165, 166, 173 
memory-model option, 21, 154 
OFFSET, 157, 159, 160 
options, 153 
overriding type, 173, 174 
parmX, 164, 173-174 
namelist parameter, 165 
X parameter, 164 
?PLM, 155, 168 
Save, 169 
sBegin, 158 
segment, 156 
segNameOFFSET, 160 
sEnd, 158 
special-definition, 170 
stack-checking option, 156 
staticX, 160 
initial Value parameter, 161 
name parameter, 160 
replication parameter, 161 
X parameter, 160 
storage allocation, 160 
symbol redefinition, 174 
?WIN, 156 
Windows prolog/epilog, 155-156 
Cmacros.inc file, 21, 153 
Code, 15 
CODE segment (Cmacro}, 156 
Code segment, — TEXT, 15-16 
CODE statement, 78 
Code swapping, 12 
codeOFFSET macro (Cmacro), 159 
Color command (Icon Editor), 185 
Color menu (Icon Editor), 182 
Column command (Font Editor), 206 
Column menu (Font Editor), 201-202 
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Combine parameter, createSeg macro 


(Cmacro), 157 


Command 


* (comment), 112, 138 

? (compute and display expression), 
112, 136 

. (dot) command, 112, 136 

< (redirect program input), 112, 137 

{ (redirect program input), 112, 137 

redirect program input an 

output), 112, 137 

} (redirect program output), 112, 137 

= (redirect symdeb input and 
output), 99, 101, 112, 137 

> (redirect symdeb output), 112, 
137 


! (shell escape), 112, 137 

a (assemble), 110, 118 

About Heapwalker, 243 

Add (Font Editor), 200-201 

Address (Heapwalker), 242 

Allocate all of memory (Heapwalker), 
242 

Allocation granularity (Shaker), 239 

ba (breakpoint address), 110, 119 

be (breakpoint clear), 110, 120, 121 

bd (breakpoint disable), 111, 120, 
121 


be (breakpoint enable), 111, 120 

bl (breakpoint list), 111, 121 

bp (breakpoint set), 108, 111, 121 

¢ (compare), 111, 121 

cel, 9, 11, 14 

Class Styles (Dialog Editor), 221, 224 

Clear (Font dito), 203 

Clear Control (Dialog Editor), 223 

Clear Dialog /Control (Dialog Editor), 
232 


Close, 108 

Color (Icon Editor), 185 

Column (Font Editor), 206 

compiler, 18 

Copy (Font Editor), 205 

Copy Dialog (Dialog Editor), 232 

Cut Dialo (Dislee Editor), 232 

d (display), 108 

d (dump memory using previous 
type}, 111, 122 

da (dump memory ASCII), 111, 122 

db (dump memory pres) 111, 122 

dd (dump memory double words), 
111, 123 

Delete (Font Editor), 201-202 

dg (display global heap), 111, 123 

dh (display local heal 111, 124 


Command omnes 
d! (dump memory, long floating 
point), 111, 124 
DOS, 99, 137, 148 
dot (.), (display current source line), 


} 
dq (display task queue), 111, 124 
Draw Straight (Icon Editor), 183 
ds (dump memory, short floating 
point), 111, 125 
dt (dump memory, ten-byte reals), 
111, 125 
dw (dump memory words), 111, 125 
e (enter), 111, 125-126 
ea (enter address), 111, 126 
eb (enter pee 111, 126 
ed (enter double-words), 111, 126 
el (enter long floating point), 111, 
127 


EQU, 154 
es (enter short floating point), 111, 
127 


et (enter ten-byte reals), 111, 127 

ew (enter words), 111, 128 

exehdr, 89 

exit (DOS), 137 

Exit (Heapwalker), 243 

f (fill), 111, 128 

Fill (Font Editor), 206 

Font Editor, 195 

Free allocated memory (Heapwalker), 
242 

Free zK of allocated memory 
(Heapwalker), 242 

g tg0} 107, 111, 128 

GC(0) and Walk (Heapwalker), 241 

GO(-1) and Hit A: (Se Rika 242 

GC(-1) and Walk (Heapwalker), 242 

GDI LocalWalk (Heapwalker), 243 

Grid (Dialog Editor), 232 

Grid (Icon Editor), 188 

h (add hexadecimal), 111, 129 

Hatched (Font Editor), 204 

Header ont Editor), 209, 211 

Heapwalker, 241 

Hotspot (Icon Editor), 187-188 

i (input from port), 111, 129 

Icon Editor, 182-183 

implib, 88 

# include, 12 

INCLUDE, 153 

Inverted (Font Editor), 204 

k (backtrace stack), 111, 129 

kt (backtrace task), 111, 129-130 

1 (load), 111, 130 

Label Segments (Heapwalker), 242 


Index 


Command (continu 


W 

LO(-1) and LocalWalk (Heapwalker), 
243 

Left= Right (Font Editor), 205 

link4, 73, 85, 150 

LocalWalk (Heapwalker), 243 

m (macro), 112, 131 

m (move), 112, 130 

make, 143 

mapsym, 96, 150 

Max objects (Shaker), 240 

mode (DOS), 99 

Module (Heapwalker), 242 

n (name), 112, 131 

Narrower (Font Editor), 200 

New (Dialog Editor), 218 

New (Icon Editor), 183-184 

New Dialog (Dialog Editor), 219, 232 

o (output to port), 112, 131 

Off (Shaker), 240 

On (Shaker), 240 

Open (Dialog Editor), 231 

Open (Font Editor), 195 

Open (Icon Editor), 188 

Order Groups (Dialog Editor) 
227-230 

p (program step), 112, 132 

Paste (Font Editor), 205 

Paste (Icon Editor), 190 

Paste Dialog (Dialog Editor), 232 

path (DOS), 148 

q (quit), 110, 112, 132 

r (register), 112, 132 

re, 11, 28-29 | 

redirection, 99, 101, 112, 137 

Refresh (Font Editor), 198-199 

Rename Dialog (Dialog Editor), 232 

Resource Properties (Dialog Editor), 
226 


Restore Dialog (Dialog Editor), 232 

Row (Font Editor), 206 

s (search), 112, 133 

s& (set. machine and source 
debugging), 109, 112, 133 

s— (set machine debugging only), 112, 
133 

s+ (set source debugging only), 109, 
112, 133 

Save (Dialog Editor), 235 

Save (Font Editor), 198, 211 

Save (Heapwalker}, 243 

Save (Icon Editor), 190 

Save As (Dialog Editor), 235 

Save As (Font Editor), 198, 211 

Save As (Icon Editor), 190 

Segmentation Test (Heapwalker), 
242 
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Command (continued) 

Select (Icon Editor), 191 

Select All (Icon Editor), 191 

Shaker, 239 

Show (Heapwalker), 242 

Show Bits (Heapwalker, 242 

Size (Font Editor), 207-208 

Size (Heapwalker), 242 

Solid (Font Editor), 203 

Standard Styles (Dialog Editor), 224, 
226, 229-231 

Start (Shaker), 240 

Step (Shaker), 240 

Stop (Shaker), 240 

symdeb, 100 

t (trace program instruction), 112, 
133 

Time interval (Shaker), 239 

Top= Bottom (Font Editor), 205 

u (display unassembled instruction), 
109, 112, 134 

Undo (Font Editor), 206 

v (view source lines), 109, 112, 134 

View Dialog (File wary 231 

View Include (Dialog Editor) 
234-235 

w (write to disk), 112, 134 

Walk Heap (Heapwalker), 241 

Wider (Font Editor), 200 

Width (Font Editor), 206 

x (examine symbol map), 104, 106, 
112, 135 

x? (examine symbol), 106, 112, 135 

xo (open symbol map), 105, 112, 
135-136 


z (set symbol value), 112, 136 
Command argument (symdeb), 113 
address, 113 

byte, 113 

command-string, 113 

count, 113 

dos-command, 113 

drive, 113 

expression, 113 

filename, 113 

id, 114 

id-list, 114 

list, 114 

pdb, 115 

range, 114 

record, 114 

register, 114-115 

symbol, 115 

value, 115 

Command parameter, make description 
file, 142 
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Command-string command argument 
(symdeb), 113 
Command-string parameter 
ba command, 119 
bp command, 121 
m sen command, 131 
macro definition (symdeb program), 
101 
Commands parameter (symdeb 
command), 101 
Comment (* command), 112, 138 
Communications port, selecting, 99 
Compact model 
application, 12 
callback function, 13 
description, 12 
fixed data segment, 12 
use, 12 
compare (¢ command), 111, 121 
Compiler 
Pascal, 11, 20 
resource, 215 
Compiling 
application, 14 
resource, 25, 28 
Compute and display expression 
? command), 112, 136 
Constant-expression field, 68 
Control 
changing order in dialog box, 228 
check-box, 50 
default push-button, 54 
dialog box, 219 
Dialog editor, 218 
See also Dialog Box 
edit, 56 
group box, 53 
icon, 57 
list box, 52 
push button, 51 
radio button, 55 
text 
centered, 49-50 
left-justified, 47-48 
right-justified, 48-49 
user access, 227-230 
user-defined, 58 
CONTROL+C key, 104 
Control class 
BUTTON, 59, 60-61 
description, 59-60 
EDIT, 59, 61-62 
LISTBOX, 59, 63-64 
SCROLLBAR, 60, 64-65 
STATIC, 59, 63 
Control ID Value field (Dialog Editor), 
218 


Control menu, 110, 216, 221 
CONTROL option 
(ACCELERATORS), 36 
CONTROL-+S key, 99 
Control statement 
CHECKBOX, 50 
CONTROL, 58 
CTEXT, 49 
DEFPUSHBUTTON, 54 
Dialog resource statement, 47, 58-59 
EDITTEXT, 56 
general form, 47 
GROUPBOX, 53 
ICON, 57 
LISTBOX, 52 
LTEXT, 47 
PUSHBUTTON, 51 
RADIOBUTTON, 55 
RTEXT, 48 
Control style 
all classes, 43 
BUTTON, 60-61 
description, 60-65 
dialog box, 223 
dialog-box control, 224, 226 
EDIT, 61-62 
LISTBOX, 63-64 
SCROLLBAR, 64-65 
STATIC, 63 
Control type {ialee ialog paitan), 218 
See also Di 
Control doe eas 58 
Convention, notational, 4 
Copy command (Font Editor), 205 
Copy Dialog command, 232 
Count command argument (symdeb), 
113 
Count parameter 
]l command, 130 
w command, 134 
cProc macro, 163 
createSeg macro, 156 
CreateWindow function, 42, 63, 64-65 
Creating resources, 11, 25, 181 
Creating resource script files, 25 
Creating symbol files {mapsym 
program), 96 
CTEXT statement (DIALOG resource 
statement), 47, 49-50 
Cursor 
background color, 188 
creating, 181 
editing, 181 
hotspot, 187-188 
mode, 184 
opening existing files, 188 


Index 


Cursor (continued) 
opening new files, 183-184 
resolution, 184 
saving files, 190 
CURSOR 
keyword, 30 
resource, 30 
resource statement, 25, 30 
Cut Dialog command, 232 
Cx field, Size window (Dialog Editor), 
217 
Oy field, Size window (Dialog Editor), 
217 


d command 
display, 108 
dump memory using previous type, 
111, 122 
D (DOUBLE WORD accessed) option 
a command), 119 
/d option (make), 144 
da (dump memory ASCII) command, 
111, 122 
_DATA data segment, 13 
Data object, type, 242 
Data segment 
~DATA, 15 
fixed, 12 
DATA segment (Cmacro), 156 
DATA statement, 79 © 
dataOFFSET macro, 159 
Data-option field (EXPORTS 
statement), 83 
db (dump memory bytes) command, 


dd (dump memory double-words) 
command, 111, 123 
Debugging 
allocation message, 107 
application, 95, 98 
application source statement display, 
109 


breakpoint setting, 108 
C-language program, 95 
command summary, 110-112 
disabling more feature, 100 
displaying 
application source statement, 109 
symbol, 106 
variable, 108-109 
executable file, 95 
external symbol, 106 
fatal exit, 110 
IBM-compatible, 101 
line number information, 13 
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Debugging (continued) 
listing symbol map, 104-105 
macro definition, 101 
memory-alloc ation 
message, 107 
reporting level, 100-101 
setting, 100-101 
multiple instance, 105 
nonmaskable interrupt, 101 
opening symbol map, 105-106 
Pascal program, 95 
quitting, 110 
redirecting input, 99 
redirecting output, 99 
remote terminal, 98 
secondary monitor, 98, 100 
setting 
breakpoints, 108 
memory allocation, 100-101 
memory allocation reporting level, 
100-101 
starting, 100 
starting the application, 107 
static variable, 108-109 
symbol 
displaying, 106 
file, 96 
map, 104-106 
symbolic (mapsym program), 96 
symdeb program, 95 
terminal, setting up, 98 
win.com argument, 100, 102, 103 
x command, 104 
Decimal mode (Dialog Editor), 218 
Decorative font (Font Editor), 210 
DEF file See Module-definition file 
Default push-button control, 54 
Def-file parameter (link4 command), 85 
# define directive, 233 
See also # define statement 
Define or execute macro (m command), 
112, 131 
# define resource directive, 26, 27 
# define statement, 66 
Definition ee jmodule: 
definition file), 
DEFPUSHBUTT NT statement, 47, 
54-55 
DefX (Cmacro), 170 
Delete button (Dialog Editor), 235 
Delete command (Font Editor) 
201-202 
Delete Marker button (Dialog Editor), 
230 


Delete Tab button (Dialog Editor), 229 
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Dependent-files parameter (make 
description file), 142 
.dependentextension parameter, 148 
Description file (make), 141 
DESCRIPTION statement, 77 
Development, language, 11 
Development program, 11 


dg (display global heap) command, 111, 


dh (display local heap) command, 111, 
124 


Diagnostic message, 247-248 
Dialog box 
adding controls, 219, 221 
adding text in controls, 221 
Cancel button, 234 
Change button, 235 
class style, 223-224 
Class Styles command, 223 
control 
adding, 219, 221 
style, 223-224, 226 
type, 219 
creating, 215, 218, 232 
See also Dialog Editor: DIALOG 
resource statement 
Delete button, 235 
deleting controls, 219, 223 
drawing borders, 218 
editing, 215 
See also Dialog Editor 
Group /Control Ordering, 227-230 
group marker, 230 
handle, 219 
memory-manager flag, 223, 226 
modifying, 231-232 
moving controls, 222 
moving groups of controls, 222 
order of controls, 228 
saving changes, 235 
scroll bar, 226 
Size box, 226 
sizing, 219 
sizing controls, 223 
standard style, 223-224, 226 
Standard Styles command, 223 
System-menu box, 226 
tab stop, 229 
visible bit, 225 
window style, 43 
Dialog-box control, 220-221 
Dialog-control statement, 47-65 
CHECKBOX, 47, 50 
CONTROL, 47, 58 
CTEXT, 47, 49 
DEFPUSHBUTTON, 47, 54 


Dialog-control statement (continued) 
EDITTEXT, 47, 56 
GROUPBOX, 47, 53 
ICON, 47, 57 
LISTBOX, 47, 52 
LTEXT, 47 
PUSHBUTTON, 47, 51 
RADIOBUTTON, 47, 55 
RTEXT, 47, 49 
Dialog Editor, 11, 215-235 
access to controls, 227-230 
adding controls, 219, 221 
adding text in controls, 221 
binary resource file, 233 
Class Styles command, 221, 224 
Clear Control command, 223 
Clear Dialog/Control command (Edit 
menu}, 232 
clearing display, 218 
control 
adding, 219, 221 
style, 223 
type, 218-219 
Control menu, 216, 221 
Copy Dialog command (Edit menu), 
232 


creating dialog box, 218 
Cut Dialog command (Edit menu), 
232 


Decimal mode, 218 
deleting a control, 219, 223 
described, 3, 215 

See also Dialog box 
dialog unit, 217 
.dlg file, 233 
Edit menu, 216, 218, 223, 232 
file, 233 
File menu, 216, 218, 231, 235 
Grid command (Edit menu), 232 
group marker, 230 
handle, 219 
Hex mode, 218 
include file, 215, 231, 233-235 
Include menu, 216, 234-235 
memory-manager flag, 223, 226 
mouse requirement, 215 
moving controls, 222 
moving groups of controls, 222 
New command (File menu), 218 
New Dialog command (Edit menu), 

219, 232 
Open command (File menu), 231 
Options menu, 216, 227-230 
Order Groups command (Options 
menu), 227-230 

order of controls, 228 


Index 


Dialog Editor (continued 


Paste Dialog command (Edit menu), 
232 
purpose, 215 
Rename Dialog command (Edit 
menu), 232 
res file, 231, 233 
resource file, 215, 233 
Resource Properties command 
(Styles menu), 226 
resource script file, 233 
Restore Dialog command (Edit 
menu), 232 
sample file, 218 
Save As command (File menu), 235 
Save command (File menu), 235 
Save command (Include menu), 235 
saving changes, 235 
scroll bar, 226 
Size box, 226 
Size window, 217, 218 
sizing 
control, 223 
dialog box, 219 
handle, 223 
Standard Styles command (Styles 
menu), 224, 226, 229-231 
starting, 216 
Styles menu, 216, 221, 223-224, 226, 
229-231 
System-menu box, 226 
tab stop, 229 
Test mode, 217 
text, adding, 221 
View Dialog command (File menu), 
231 
View Include command (Include 
menu), 234-235 
Work mode, 217 


Dialog-option statement, 43 


CAPTION, 43, 45 
CLASS, 43, 46 
MENU, 43, 46 
STYLE, 41, 43 


DIALOG resource, 25, 40 
DIALOG resource statement, 25, 40 


control class, 59-60 
dialog-control statement, 47-65 
CHECKBOX, 47, 50 
CONTROL, 47, 58 
CTEXT, 47-49 
DEFPUSHBUTTON, 47, 54 
EDITTEXT, 47, 56 
GROUPBOX, 47, 53 
ICON, 47, 57 
LISTBOX, 47, 52 
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DIALOG resource statement 
(continued) 
dialog-control statement (continued) 
LTEXT, 47 
PUSHBUTTON, 47, 51 
RADIOBUTTON, 47, 55 
RTEXT, 47, 48 
dialog-option statement, 43 
CAPTION, 43, 45 
CLASS, 43, 46 
MENU, 43, 46 
STYLE, 41, 43 
load-option field, 41 
mem-option field, 41 
syntax, 4] 

DIALOG statement See DIALOG 
resource; DIALOG resource 
statement 

DIALOG template, 40-41 

Dialog unit, described, 217 

Dialog-box control 

DialogBox function, 42 

Directive, 65-68 

# define, 26, 27, 66, 67, 233 
description, 65 

# elif, 67, 68 

#: else, 67, 68, 69 
# endif, 67, 68, 69 
# if, 68, 69 

# ifdef, 67, 68, 69 
4 ifndef, 67, 68, 69 
# include, 10, 25 
resource, 26, 27 

# undef, 66-67 

Disable breakpoint (bd command), 111, 
120, 121 

DISCARDABLE keyword 

DIALOG resource statement, 41 

MENU resource statement, 37 

RCDATA resource statement, 33 

single-line resource statement, 31 

STRINGTABLE resource statement, 
34 

user-defined resource statement, 32 

Disk file, 17 

Display box (Icon Editor), 182 

Display current source line 
See dot (.) command 

Display expression command 
See ? command 

Display global heap (dg command), 
1 23 


Display local heap (dh command), 111, 
124 


Display static variable (d command), 
108 
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Display task queue (dq command), 111, 
124 


Display unassembled instructions 
(a command), 109, 112, 134 
Display symbol See x? command 
Display symbol map See x command 
dl ump memory, long floating point) 
command, 111, 124 
dig file (Dialog Editor), 233 
Dontcare font (Font Editor), 210 
DOS 
command.com, 137 
commands, 99 
exit command, 137 
filename format, 84 
mode command, 99 
path command, 148 
program, 17 
tools, 3 
See also specific tool 
Dos-command 
command argument (symdeb), 113 
parameter (! command), 137 
dot (.) command, 112, 136 
dq (dump task queue) command, 111, 
124 


Drawing, new, 183-184 

Drawing box (Ieon Editor), 182-183 

Drawing grid (Icon Editor), 188 

Drive command argument (symdeb), 
113 

Drive parameter 

] command, 130 
w command, 134 
ds (dump memory, short floating 
oint) command, 111, 125 

DS_ ABSALIGN, 41, 42 

DS_SYSMODAL, 438 

ds register, 19, 249-251 

dt (dump memory ten-byte reals) 
command, 111, 125 

Dump ASCII command 
See da command 

Dump bytes command 
See db command 

Dump command Seed command 

Dump double-words command 
See dd command 

Dump long reals command 
See dl command 

Dump memory ASCII (da command), 
111, 122 

Dump memory bytes (db command), 
111, 122 

Dump memory double words 
(ad command), 111, 123 


Dump memory, long floating point 
(all command), 111, 124 

Dump memory, short floating point 
ds command), 111, 125 

Dump memory ten-byte reals 
(at command), 111, 125 

Dump memory using previous type 
C command), 111, 122 

Dump memory words (dw command), 
111, 125 

Dump short reals command 
See ds command 

Dump task queue command 
See dq command 

Dump ten-byte reals command 
See dt command 

Dump words command 
See dw command 

dw (dump memory words) command, 
111, 125 

Dynamic linking, 88 

Dynamic-link library, 18 


e (enter using previous type) command, 
411, 125-126 
ea (enter address) command, 111, 126 
eb (enter eye command, 111, 126 
ed (enter double-words) command, 111, 
126 
EDIT class 
control style, 61-62 
default style, 57 
Edit control, 56 
dialog box, 220 
EDIT control class, 59 
Edit menu 
Icon Editor, 182, 187 
commands (Dialog Editor), 232 
Dialog Editor, 216, 218, 223 
Font Editor, 198-199, 206 
Editing 
bitmaps See Icon Editor 
cursors See Icon Editor 
dialog box, 215 
See also Dialog Editor 
font, 212 
See also Font Editor 
icon See Icon Editor 
include file, 235 
EDITTEXT statement, 47, 56-57 
el (enter long floating point) command, 
111, 127 
# elif resource directive, 26, 27 
# elif statement, 67, 68 
# else resource directive, 26, 27 


Index 


# else statement, 67, 68, 69 
Enable breakpoint (be command), 111, 
120 


# endif resource directive, 26, 27 

# endif statement, 67, 68, 69 

Enter address command 
See ea command 

Enter memory ASCII (ea command), 
111, 126 

Enter memory bytes (eb command), 
111, 126 

Enter command Seee command 

Enter double words (ed command), 
111, 126 

ENTER key, 62, 233-234 

Enter long floating point (el command), 
111, 127 

Enter long reals command 
See el command 

Enter short floating point 
(es command), 111, 127 

Enter short reals command 
See es command 

Enter ten-byte reals (et command), 
111, 127 

Enter using previous type 
(e command), 111, 125-126 

Enter words (ew command), 111, 128 

Entry-option field (IMPORTS 
statement), 84 

Entry point, application, 13 

Entryname field (EXPORTS 
statement), 82 

entryname option, 84 

entryordinal option, 84 

environ variable, 16 

Epilog (Windows), 14, 19, 21, 155 

EQU command (Cmacro), 154 

Error (Cmacro), 171 

errn$, 172 

errnz, 172 

es (enter short floating point) 
command, 111, 127 

ES... AUTOHSCROLL, 62 

ES_ AUTOVSCROLL, 62 

ES_ CENTER, 61 

ES_ LEFT, 57, 61 

ES MULTILINE, 62 

ES_ NOHIDESEL, 62 

ES_ RIGHT, 61 

Escape character, MENUITEM 
statement, 38 

ESCAPE key, assigning ID value, 233-234 

et (enter ten-byte reals) command, 111, 
127 


Event field (ACCELERATORS), 35 
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ew (enter words) command, 111, 128 
Examine symbol (x? command), 106, 
112, 135 
Examine symbol map (x command), 
104, 106, 112, 135 
Executable file 
debugging, 95 
examining header, 89 
testing, 95 
Executable file header, 89 
Executable-file parameter 
rec command), 29 
Exe-file parameter (link4 command), 85 
Exe-filename parameter (exehdr 
command}, 89 
exehdr command, 89 
Exit command (Heapwalker), 243 
Exit menu (Icon Editor), 182 
Exported function, 19 
Exportname field (EXPORTS 
statement), 82 
EXPORTS statement, 14, 74, 82-83 
Expression (symdeb), 117 
command argument, 113 
parameter 
? command, 136 
errnz macro, 172 
ExternX (Cmacro), 162 


f (fill) command, 111, 128 
f option, 101 
ar call, 13 
Far keyword, 13, 19 
FarPtr (Cmacro), use with cCall, 171 
Fatal exit, 110 
Fatal message, 247-248 
Fatal-exit message, 110 
FatalExit function, 15 
fclose function, 17 
fgets function, 17 


ile 
Bitmap, 183-184, 188 
cmacros.inc, 21, 153 
Cursor, 183-184, 188 
description (make), 141-143 
disk, 17 

font See Font Editor 
fontedit.exe, 195 

header, executable, 89 
heapwalk.exe, 241 

Icon, 183-184, 188 
iconedit.exe, 181 

include, 215, 231, 233-235 
inference rules (make), 147 
maintaining, 141 


264 


File (continued) 
map, 96-98 
module-definition, 11 
res, 231 
resource, 25, 231, 233 
resource script, 11, 25-26, 27, 215 
See also Resource script file 
sample (Dialog Editor), 218 
script, 11, 27 
See also Resource script file 
shaker.exe, 239 
source, Li, 14 
symbol, 96-98, 100, 101, 102-103 
See also Symbol file 
symbol map, 104-106 
tools.ini, 148 
updating, 141 
windows.h, 11, 20, 43 
File format 
module-definition file, 75 
resource file, 25 
File header, executable, 39 
File menu, 182, 183, 188-190 
Dialog Editor, 216, 218, 231, 235 
Font Editor, 195-197, 211 
Heapwalker, 243 
Filename 
command argument (symdeb), 113 
field 
# include statement, 65 
single-line resource statement, 31 
STUB statement, 84 
user-defined resource statement, 32 
format (DOS), 84 
parameter 
option (symdeb command), 
101 


make command, 143 
n command, 131 
rc command, 29 
Fill (f command), 111, 128 
Fill menu (Font Editor), 203-205 
FIXED keyword 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
single-line resource statement, 31 
STRINGTABLE resource statement, 
34 
user-defined resource statement, 32 et 
Fixed-pitch font, 207-208, 212 
Flag, memory-manager, 223, 226-227 
Flag name (symdeb), listing, 115 
Floating-point option 
alternate math, 18 
coprocessor/emulator math, 16, 18 


{nt filename extension, 211 
Font 
decorative, 210 
Dontcare, 210 
family name, 210, 211 
fixed-pitch, 207-208, 212 
italic, 210 
modern, 210 
raster, 195 
resizing, 207-208 
Roman, 210 
script, 210 
strikeout, 210 
swiss, 210 
underline, 210 
variable-pitch, 200, 207-208, 212 
vector, 195 
Font Editor, 11, 195-212 


Add command (Row menu), 200, 201 


ANSI character set, 210 
break character, 210 
canceling changes, 206 
changing font header, 209, 211 
character 
canceling change, 199 
changing width, 200 
editing, 198 
saving, 198 
saving changes, 206-207 
selecting, 198 
character pixel height, 207 
character set, 210 
character-viewing window, 197 
character window, 197 
clearing, 203 
filling, 203-204 
hatch pattern, 204 
inverting, 204 
reversing, 205 
Clear command (Font Editor), 203 
Clipboard, 205 
Column menu, 201-202 
Copy command (Fill menu), 205 
copyright, 209 
decorative font, 210 
default character, 210 
Delete command (Column menu), 
202 
Delete command (Row menu), 201 
described, 3, 195 
dontcare font, 210 
Edit menu, 198-199, 206 
editing tips, 212 
external leading, 209 
face name, 209 
features, 197 
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Font Editor (continued) 


File menu, 195-197, 211 
filename, 209 
Fill menu, 203-205 
filling character window 
hatched pattern, 204 
solid block, 203 
first character, character value, 207 
fixed-pitch font, 207, 208 
font family, 210 
Font menu, 207-209, 211 
font window, 198 
fontedit.exe file, 195 
Hatched command (Fill menu), 204 
Header command (Font menu), 209, 
211 
Header dialog box, 209 
height of ascent, 209 
internal leading, 209 
Inverted command (Fill menu), 204 
italic font, 210 
last character, character value, 207 
Left= Right command (Fill menu), 
205 


loading, 195 

loading font files, 195 

main window, 197 

modern font, 210 

mouse requirement, 195 

Narrower command (width menu), 
200 


nominal horizontal resolution, 209 
nominal point size, 209 
nominal vertical resolution, 209 
OEM character set, 210 
Open command (File menu), 195 
Paste command (Fill menu), 205 
pitch, 208 
pixel 
coloring, 199 
copying columns, 201-202 
copying rows, 200-201 
deleting columns, 202 
deleting rows, 201 
Refresh command (Edit menu) 
198-199 
resizing fonts, 207-208 
roman font, 210 
Row menu, 200-201 
Save As command (File menu), 198, 
211 
save As dialog box, 211 
Save command (File menu), 198, 211 
saving font files, 211 
script font, 210 
Size command (Font menu), 207-208 
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Font Editor (continued) 
Size dialog box, 208 
Solid command (Fill menu), 203 
starting, 195 
strikeout font, 210 
swiss font, 210 
Top= Bottom command (Fill menu), 
205 
underline font, 210 
Undo command (Edit menu), 206 
undoing changes, 206 
variable-pitch font, 207, 208 
weight, 208 
Wider command (Width menu), 200 
Width menu, 200 
window, 197 
Font file 
See also Font Editor 
creating, 195 
editing, 195 
header, 209, 211 
FONT keyword (single-line resource 
statement), 30 
Font menu (Font Editor), 207-209, 211 
FONT resource, 30 | | 
FONT resource statement, 25, 30 
Font window (Font Editor), 198. 
Fontedit.exe file, 195 
—FPa command, 18 
—FPe command, 18 
—FPi command, 18 
fprintf function, 17 
Frame control (dialog box), 220 
fread function, 17 
Free allocated memory command 
(Heapwalker), 242 
Free 2K of allocated memory command 
(Heapwalker), 242 
fscanf function, 17 
Function 
CO language, 17 
C run-time, 17, 19-20, 249-251 
callback, 13, 19, 21 
calloc, 17 
CreateWindow, 42, 63, 64-65 
DialogBox, 42 
exported, 19 
FatalExit, 15 
fclose, 17 
fgets, 17 
fprintf, 17 
fread, 17 
fscanf, 17 
fwrite, 17 
gets, 17 
GlobalAlloc, 241 
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Function (continued) 
GlobalLock, 247 
GlobalRealloc, 241 
GlobalUnlock, 247 
kernel, 19 
LoadString, 34 
local, 14 
Local Alloc, 17 
LocalLock, 247 
LocalUnlock, 247 
malloc, 17 
memory-allocation, 17 
memory-management, 17 
printf, 17 
run-time, 251-253 
_ setargv, 16 
—setenvp, 16 
TranslateAccelerator, 35 
Windows, 13 
WinMain, 13, 21, 108 

Function macro (Cmacro), 163 

fwrite function, 17 


g (go) command, 107, 111, 128 
g (start application) command 
See g (go) command) 

GC(0) and Walk command 
(Heapwalker), 241 
acres and Hit A: command 
eapwalker), 242 
oo and Walk command 
(Heapwalker), 242 
GDI library, symbol file, 102 
GDI LocalWalk command 
(Heapwalker), 243 
gets function, 17 
Global heap, viewing, 241 
Global window style, 224 
GlobalAlloc function, 241 
GlobalLock function, 247 
GlobalRealloc function, 241 
GlobalUnlock function, 247 
GlobalX macro (Cmacro), 161 
Go (g command), 107, 111, 128 
GRAYED option 
MENUITEM statement, 38 
POPUP statement, 39 
Grid command 
Dialog Editor, 232 
Icon Editor, 188 
Group Bit check box, 230 
Group box 
BUTTON class, 53 
dialog-box control, 220 
Group box control, 50 


Group box (dialog box), 220 

Group marker, 230 

Group Marker button (Dialog Editor), 
230 

GROUPBOX statement, 47, 53-54 

Group /Control Ordering dialog box 
(Dialog Editor), 227-230 

~—Gs option, 15 

—Gw option, 14, 19 


h (add hexadecimal) command, 111, 
129 
ye See /help option 
andle 
dialog box, 219 
Dialog Editor, 223 
Hatch pattern, 204 
Hatched command (Font Editor), 204 
Header (Font ae 209, 211 
Header command (Font Editor), 209, 
211 
Header dialog box (Font Editor), 209 
Heap space, application, 74 
HEAPSIZE statement, 77 
Heapwalk.exe file, 241 
Heapwalker 
About Heapwalker command, 243 
Address command, 242 
Allocate all of memory command, 
242 
application, 241 
commands, 241 
described, 3 
Exit command, 243 
File menu, 243 
Free allocated memory command, 
242 
Free 2K of allocated memory 
command, 242 
GC(0) and Walk command, 241 
GC(-1) and Hit A: command, 242 
GC{-1) and Walk command, 242 
GDI LocalWalk command, 243 
Label Segments command, 242 
LC(-1) and LocalWalk command, 
243 
LocalWalk command, 243 
Module command, 242 
Object menu, 242, 243 
overview, 239 
Save command, 243 
Segmentation Test command, 242 
Show Bits command, 242 
Show command, 242 
Size command, 242 
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Heapwalker (continued) 
Sort menu, 242 
starting, 241 
Walk Heap command, 241 
Walk menu, 241, 242 
window, 241 

Height field 
CHECKBOX statement, 51 
CONTROL statement, 59 
CTEXT statement, 50 
DEFPUSHBUTTON statement, 55 
DIALOG resource statement, 41 
EDITTEXT statement, 57 
GROUPBOX statement, 54 
ICON statement, 58 
LISTBOX statement, 53 
LTEXT statement, 48 
PUSHBUTTON statement, 52 
RADIOBUTTON statement, 56 
RTEXT statement, 49 

sear option (MENUITEM statement), 


help option, 86 
ex command See h command 
Hexadecimal mode (Dialog Editor), 218 
Horizontal scroll bar (dialog box), 220 
Hotspot command (Icon Editor) 
187-188 


i (input from port) command, 111, 129 
ee fetch) option 
(ba command), 119 
/i option (make), 144 
ibm option, 101 
con 
background color, 188 
creating, 181 
dialog-box control, 220-221 
hotspot, 187-188 
mode, 184 
opening existing file, 188 
opening new file, 183-184 
resolution, 184 
saving file, 190 
Icon (dialog box), description, 220 
Icon control, 57 
Icon Editor, 9, 181-191 
background, 188 
bitmap mode, 184 
clearing drawing box, 183 
Color menu, 182, 185 
commands, 182 
cursor mode, 184 
default pen color, 183 
default pen color, bitmap, 185 
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Icon Editor (continued) 
described, 3, 181 
display box, 182 
display format, 184 
Draw Straight command (Options 
menu), 183 
drawing, 183 
box, 182-183 
grid, 188 
Edit menu, 187, 190 
File menu, 183-184, 188, 190 
file opening, 183-184, 188 
Grid command (Options menu), 188 
hotspot, 187-188 
icon mode, 184 
menu, 182 
menu bar, 182 
Mode menu, 188 
mouse requirement, 181 
New command (File menu), 183-184 
Open command (File menu), 188 
opening existing file, 188 
opening new file, 183-184 
Options menu, 183, 188 
Paste command (Edit menu), 190 
pen color, 185 
pen size, 186 
Pensize menu, 186 
resolution, 184 
Save As command (File menu), 190 
Save command (File menu), 190 
saving files, 190 
Select All command (Edit menu), 191 
Select command (Edit menu), 191 
starting, 181 
window, 182 
ICON keyword (single-line resource 
statement), 30 
ICON resource, 30 
ICON resource statement, 25, 30 
ICON statement, 47, 57-58 
iconedit.exe file, 181 
Id command argument (symdeb), 114 
Id field 
CONTROL statement, 58 
CTEXT statement, 50 
CHECKBOX statement, 51 
DEFPUSHBUTTON statement, 55 
EDITTEXT statement, 56 
GROUPBOX statement, 54 
ICON statement, 58 
LISTBOX statement, 52 
LTEXT statement, 48 
PUSHBUTTON statement, 52 
RADIOBUTTON statement, 56 
RTEXT statement, 49 
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Id-list command argument (symdeb), 
114 | 
Id-list parameter, 120 
Id parameter 
bp command, 121 
m command, 131 
ID value (dialog-box control), 233 
ee field (ACCELERATORS), 36 
i 
resource directive, 26, 27 
statement, 68, 69 
# ifdef 
resource directive, 26, 27 
statement, 67, 68, 69 
# ifndef 
resource directive, 26, 27 
statement, 67, 68, 69 
Immediate breakpoint (symdeb) 
See SYS REQ key 
implib command, 88 
Imp-lib-name parameter (implib 
command}, 88 
IMPORTS statement, 83-84 
entry-option field, 84 
entryname parameter, 84 
entryordinal parameter, 84 
internal-option field, 83 
modulename field, 84 
syntax, 83 
INACTIVE; option 
MENUITEM statement, 38 
POPUP statement, 39 
include 
file, 215, 231, 233-235 
menu (Dialog Editor), 234-235 
# include 
directive, 12, 215 
resource directive, 26, 27, 28 
STYLE statement, use in, 43 
statement, 65-66 
INCLUDE 
command (Cmacro), 153 
environmental variable, 28, 66 
Inference rule, 147 
InitialValue parameter, globalX macro 
(Cmacro}, 161 
Initial Value parameter, staticX macro 
(Cmacro), 161 
Input, redirecting, 99 
Input command See icommand 
Input from port (i command), 111, 129 
Internal-option field (IMPORTS 
statement), 83 
Internalname field (EXPORTS 
statement}, 82 


Interrupt, nonmaskable, use in 
debugging, 101 

Interrupt key, breaking execution of 
application, 108 

Inverse Screen color, 185 

Inverted command (Font Editor), 204 

Italic font (Font een 210 

Item-definition field (MENU resource 
statement), 37 

Item-definitions field (POPUP 
statement), 39 


k (backtrace stack) command, 111, 129 
Kernel 
function, 19 
library, symbol file, 100 
Key 
CONTROL+C, 104 
SCROLL LOCK, 103 
symdeb, 103-104 
SYS REQ, 103 
Keyword 
BITMAP, 30 
CURSOR, 30 
DISCARDABLE 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
single-line resource statement, 31 
STRINGTABLE resource 
statement, 34 
user-defined resource statement, 32 
far, 13, 19 
FIXED 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
single-line resource statement, 31 
STRINGTABLE resource 
statement, 34 
user-defined resource statement, 32 
FONT, 30 
ICON, 30 
LOADONCALL 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
single-line resource statement, 31 
STRINGTABLE resource 
statement, 34 
user-defined resource statement, 32 
MOVEABLE 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
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Keyword (continued) 
MOVEABLE (continued) 
single-line resource statement, 31 
STRINGTABLE resource 
statement, 34 
user-defined resource statement, 32 
Pascal, 13 
PRELOAD 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
single-line resource statement, 31 
STRINGTABLE resource 
statement, 34 
user-defined resource statement, 32 
rcinclude, 28, 215, 233 
kt (backtrace task stack) command, 
111, 129-130 


] (load) command, 111, 130 
i mn 97 
abel parameter, errn$ macro 
Cmacro}, 172 
Labe Segments command 
Heapwalker), 242 
LabeIX macro (Cmacro), 162 
Language 
assembly, 141 
assembly language, 20 
development, 11 
high-level, 141 
Pascal, 11, 20 
Large model, 12-13 
LBS. MULTIPLESEL, 63 
LBS_ NOREDRAW, 64 
LBS_ NOTIFY, 53, 63 
LBS_ SORT, 53, 64 
oo) and LocalWalk command 
eapwalker), 243 
Leading, 209 
bole command (Font Editor), 
2 
li (linenumbers optio n) 86, 97 
ib-files parameter (link4 command), 
85 


Library 
C language, 16, 19, 22 
C run-time, 17, 22 
dynamic linking, 18, 88 
EXPORTS statement, 74 
GDI, symbol file, 102 
import, 88 
kernel, symbol file, 102 
LIBRARY statement, 74 
linking, 18, 73, 88 
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Library (continued) 
module-definition file, 74 
pointer, 20 
run-time, 16 
symbol file, 102 
Windows, 16, 19-20, 22, 73 

Library module, 76 

LIBRARY statement, 74, 76 

—LIM32 option (re command), 29 

( linenumbers option, 86, 97 

ink4, 11, 16, 18 
/alignment option, 86 
C language hbrary, 16 
command, 73, 85, 150 
def-file parameter, 85 
described, 3 
dynamic linking, 86 
exe-file parameter, 85 
filename extension, default, 86 
/help option, 86 
import hbrary, 86 
lib-files parameter, 85 
library, 86 
/linenumbers option, 86 
/map option, 87 
map-file parameter, 85 
module-definition file, 76 
pod teulslibreryecatch (not used), 


/nofarcalltrans option, 87 

/noignorecase option, 87 

object-files parameter, 85 

options, 86-88 

options parameter, 85 

/packcode option, 87 

/pause option, 87 

/segments option, 87 

/stack option, 87 

syntax, 85 

warnfixup option, 87 

Linking 

application, 73, 85 

dynamic, 88 

library, 73, 88 

link4 option, 86-88 

module-definition file, 73 
List box, 52 
List box (dialog box), description, 220 
List-box control, 52 
List breakpoint {b] command), 111, 121 
List command argument (symdeb), 114 
List parameter 

e command, 125, 126 

ea command, 126 

eb command, 126 

f command, 128 
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List parameter (continued) 
s command, 133 
LISTBOX class 
control style, 63-64 
style, 53 
LISTBOX control class, 59 
LISTBOX control style, 63-64 
LISTBOX statement, 47, 51-52 
Load (1 command), 111, 130 
Loading (Font Editor), 195 
LOADONCALL keyword 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
single-line resource statement, 31 
STRINGTABLE resource statement, 
34 
user-defined resource statement, 32 
Load-option field 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
single-line resource statement, 31 
STRINGTABLE resource statement, 
34 
user-defined resource statement, 32 
LoadString function, 34 
Local Alloc function, 17 
Local function, definition, 14 
Local variable, 20 
LocalLock function, 247 
LocalUnlock function, 247 
LocalWalk command (Heapwalker), 
243 
LocalX (Cmacro), 165, 173 
LogName parameter, createSeg macro 
(Cmacro), 157 
Long pointer, 20 
LTEXT statement, 47-48 


m (macro) command, 112, 131 
m (move) command, 112, 130 
m option, 100 
acro 
Cmacro, 153 
macro definitions, make, 145 
nesting, 146 
special name, 147 
Macro Assembler, 11, 20 
Cmacro, use of, 153 
described, 3 
Macrocommand Seem (macro) 
command 
Macrodefinitions parameter (make 
command), 143 


Main window (Font Editor), 197 
Maintaining programs, 141 
make 
/d option, 144 
dependent file, 142-143 
described, 3, 141 
description file, 141-143 
command parameter, 142 
dependent-files parameter, 142 
format requirement, 142, 145 
targetfile parameter, 142 
example, 149-150 
/i option, 144 
inference rule, 147, 148 
macro definition, 145 
name parameter, 145 
nesting, 146 
value parameter, 145 
message, 144 
/n option, 144 
/s option, 144 
special macro names ($*, $+«, $@ ), 
147 
starting, 143 
target file, 142-143 
make command, 143-144 
malloc function, 17 
Map See Map file; Symbol map 
(ep option, 87, 97, 98 
file, 96 
a ra parameter (link4 command), 
D 


Mapfilename parameter (mapsym 
command), 96 
Mapname parameter, symbol 
specification (x? command), 135 
mapsym command, 96, 150 
mapsym program, 96-97 
Masm, 3, 11 
Max objects command (Shaker), 240 
Maximize box, 44 
Medium model 
application, 12, 13 
description, 12 
use, 12 
Mem-option field 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
single-line resource statement, 31 


STRINGTABLE resource statement, 


34 
user-defined resource statement, 32 
memC option (Cmacro), 21, 154 
memH option (Cmacro), 154 
memL option (Cmacro), 21, 154 


Index 


memM option (Cmacro), 21, 154 


Memory 


allocation 

applications, 241 

setting reporting level, 100 
movable (Shaker), 239 
movement, 239 
system, allocation status, 239 


Memory-allocation function, 17 


Memory-allocation message, 107, 108 
See also /w option 


Memory-management function, 17 
Memory-manager flag, 223, 226 


Memory-model option, compact 
See memC option 
Memory-model option, huge 
See memH option 
Memory-model option, large 
See memL option 
Memory-model option, medium 
See memM option 
Memory-model option, small 
See memS option 
memS option (Cmacro), 21, 154 
Menu 
Color (Icon Editor), 182, 185 
Column (Font Editor), 201-202 
Control, 108 
Control (Dialog Editor), 216, 221 
Edit (Dialog Editor), 216, 218, 223, 
232 


Edit (Font Editor), 198-199, 206 
Edit (Icon Editor), 182, 187, 190 
Exit (Icon Editor), 182 
File (Dialog Editor), 216, 218, 231, 
235 
File (Font Editor), 195, 211 
File (Heapwalker}, 244 
File (Icon Editor}, 182-184, 188, 190 
Fill (Font Editor), 203-205 
Font (Font Editor), 207-209, 211 
Icon Editor, 182 
Include (Dialog Editor), 216, 234-235 
Mode (Icon Editor), 188 
Object (Heapwalker), 242 
GDI LocalWalk command, 244 
LO(-1) and LocalWalk command, 
244 
LocalWalk command, 242 
Show Bits command, 242 
Show command, 242 
Options (Dialog Editor), 216, 227-230 
Options (Icon Editor), 182-183, 188 
Parameter chek et 239 
Allocation granularity command, 
239 
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Menu (continued) 

Parameter (Shaker) (continued) 
Max objects command, 240 
Time interval command, 239 

Pensize (Icon Editor), 182, 186 

Row (Font Editor), 200-201 

Shake (Shaker), 240 

Show State (Shaker), 240 

Sort (Heapwalker), 242 

Styles (Dialog Editor), 216, 221, 223, 

224, 226, 229-231 
Walk (Heapwalker), 241, 242 
Width (Font Editor), 200 
MENU resource, 36-40 
See also MENU resource statement 
MENUITEM SEPARATOR 
statement, 40 
MENUITEM statement, 38-39 
POPUP statement, 39-40 
MENU resource statement, 25, 36-40 
item-definition field 
MENUITEM statement, 37 
POPUP statement, 37, 39 

load-option field, 37 

mem-option field, 37 

menulD field, 37 

syntax, 36 

MENU statement (DIALOG resource 
statement), 46 
MENUBARBREAK option (POPUP 
statement), 39 
MENUBR. option 
MENUITEM statement, 38 
POPUP statement, 39 
MenulD field (MENU resource 
statement}, 37 
MENUITEM statement, 37, 38-39 
MENUITEM SEPARATOR statement, 


40 
Menuname field (MENU statement), 
43, 46 
Message 
allocation, 107 
diagnostic, 247-248 
fatal, 247-248 
fatal-exit, 110 
hexadecimal library, 247-248 
listing, 247-248 
make, 144 
memory-allocation, 107 
WM_ COMMAND, 35, 234 
WM_ SYSCOMMAND, 35 
Minialloc field (SEGMENTS 
statement), 81 
Minimize box, 44 
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Mod-def-file parameter (implib 
command), 88 
ode 
cursor, 184 
Decimal (Dialog Editor), 218 
Hexadecimal (Dialog Editor), 218 
icon, 184 
Test (Dialog Editor), 217 
Work (Dialog Editor), 217 
mode command, 99 
Mode menu, 188 
Modern font (Font Editor), 210 
Module command (Heapwalker), 242 
Module-definition file, 11 
application, 73 
CODE statement, 78-79 
creating, 73 
DATA statement, 79-80 
definition, 73 
DESCRIPTION statement, 77 
EXPORTS statement, 74, 82-83 
HEAPSIZE statement, 77 
IMPORTS statement, 83-84 
hbrary, 74 
LIBRARY statement, 74, 76 
module statement, description, 75 
NAME statement, 73, 75-76 
SEGMENTS statement, 81-82 
STACKSIZE statement, 77-78 
STUB statement, 84-85 
Module name jappienion), 73 
Module-name field, memory-allocation 
message (symdeb), 107 
Module statement (module-definition 
file), description, 75 
Modulename field 
IMPORTS statement, 84 
NAME statement, 75 
Monitor, secondary, 98-99 
More feature, disabling, 100 
Mouse requirement 
Dialog Editor, 215 
Font Editor, 195 
Icon Editor, 181 
Move (m command), 112, 130 
MO LE keyword 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
single-line resource statement, 31 
STRINGTABLE resource statement, 
34 
user-defined resource statement, 32 
Movable memory (Shaker), 239 
MS-DOS See DOS 


MS-DOS Executive, starting 
application, 107 
MS-DOS Executive window, 195, 216 
quitting symdeb, 110 
starting Heapwalker, 241 
starting Shaker, 239 
—multinst option (re command), 29 
Multiple-line resource statement, 25 
ACCELERATORS, 35 
DIALOG, 40 
MENU, 36 
RCDATA, 33 
STRINGTABLE, 34 


n (name) command, 112, 131 
{a option, 97, 101, 144 
ame command Seen command 
Name field, 66, 67 | 
Name parameter 
FarPtr macro (Omacro), 171 
globalX macro (Cmacro), 161 
staticX macro (Cmacro), 160 
macro definition (make), 145 
NAME statement, 73, 75-76 
NamelD field 
DIALOG resource statement, 41 
single-line resource statement, 30 
user-defined resource statement, 32 
Namelist parameter 
Arg macro (Cmacro), 170 
DefX macro (Cmacro), 171 
externX macro (Cmacro), 162 
labelX macro (Cmacro), 163 
localX parameter (Omacro), 166 
parmX macro (Omacro), 165 
Naming 
modules, 73 
resources, 26-29 
symbol files, 102 


Narrower command (Font Editor), 200 


—ND option, 15 
New-address field, memory-allocation 
message (symdeb), 107 
New command 
Dialog Editor, 218 
Icon Editor, 183-184 
New Dialog command (Dialog Editor), 
219, 232 
NODATA keyword (EXPORTS 
statement), 83 
/nodefaultlibrarysearch option (not 
used), 88 
/nof See /nofarcalltrans option 
/nofarcalltrans option, 87 
/noi See noignorecase option 


Index 


noignorecase option, 87 
OINVERT option | 
(ACCELERATORS), 36 
Nonmaskable interrupt, use in 
debugging, 101 
Notational convention 
bold type, 4 
double brackets (| |), 4 
ellipsis (...), 4 
italic type, 4 
small capital letters, 5 
—NT option, 15 
Number parameter 
aut definition (symdeb program), 
1 


/packcode option, 87 
/segments option, 87 
/w option (symdeb command), 100 


o (output to port) command, 112, 131 

Object menu (Heapwalker), 242-243 

Object-files parameter (link4 
command), 85 

—Od option, 13 

OEM character set, 210 

Off command (Shaker), 240 

Offset field (dh command), 124 

OFFSET macro (Omacro), 157, 159, 
160 


Offset parameter, FarPtr macro 
(Cmacro), 171 
Old-address field, memory-allocation 
message (symdeb), 107 
On command (Shaker), 240 
Open command 
Dialog Editor, 231 
Font Editor, 195 
Icon Editor, 188 
Open map /segment (xo command), 
105, 112, 135-136 
Opening symbol map (symdeb) 
See xo command 
Operator 
binary, 117 
symdeb, 117-118 
unary, 117 
Option 
/@, 101, 131 
—AC, 12 
—-AL, 12 
/alignment, 86 
12 


As, 19 
-AS, 12, 19 
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Option (continued) 
—Aw, 1 
—c, 14 
C compiler, 14 
Cmacro, memory-model, 154 
/d, 144 
designator, 102 
101 
floating-point 
alternate math, 18 
coprocessor/emulator math, 16, 18 
—Gs, 15 


, lmenumbers, 86, 97 
ink4, listing, 86-88 


m, 100 
/map, 87, 97, 98 
memC, 21, 154 
memH, 154 
memL, 21, 154 
memM, 21, 154 
mems, 21, 154 
/n, 97, 101, 114 
“ND, 15 
/nodefaultlibrarysearch (not used), 

88 


/nofarcalltrans, 87 
/noignorecase, 87 


—Od, 15 
—Os, 15 
/packcode, 87 
pause, 87 
?PLM, 19 
—r, 29 
/s, 144 
/segments, 87 
/stack, 87 
stack-checking (Cmacro}, 156 
startup command, 101 
symdeb, 100-102 
w, 100-101 
warnfixup, 87 
(WIN, 21 
/x, 101 
—Zd, 15, 97 
—Zp, 15 
Option parameter 
ba command, 119 
rc command, 29 
Optionlist field 
MENUITEM statement, 38 
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Optionlist field (continued) 
POPUP statement, 39 
Options menu, 182 
Dialog Editor, 217, 227-230 
Icon Editor, 188 
Options parameter os 
link4 command, 85 
make command, 143 
symdeb command, 100 
Order Groups command (Dialog 
Editor), 227-230 
Ordinal-option field (EXPORTS 
statement), 83 
—QOs option, 15 
Output, redirecting, 99, 100 
Output command See o command 
Output to port (o command), 112, 131 
Owner field (dg command), 123 


p (program step) command 
/pac See /packcode option 
packcode option, 87 

acked structure, definition, 15 
Parameter, 29 
Parameter menu (Shaker), 239 
Parameter-option field (EXPORTS 

statement), 83 

ParmX (Cmacro), 164, 173-174 
Pascal 

calling convention, 21 

compiler, 11, 20 

keyword, 13 

language, 11, 20 

program, debugging, 95 
Paste command 

Font Editor, 205 

Icon Editor, 190 
Paste Dialog command, 232 
Path command (make program), 148 
PATH environmental variable, 84 
/pau See /pause option 


ppanke option, 87 
db 


command argument (symdeb), 115 
value (kt command), 129 

Pen color 
bitmap default, 185 
default, 183 oa 
Icon Editor, 185 

Pen size (Icon Editor), 186 

Pensize menu (Icon Editor), 186 

Pixel 
coloring in Font Editor, 199 


Pixel (continued) 
copying 
column, 201-202 
row, 200-201 
deleting 
column, 202 
row, 201 
filling character window, 204 
foreground, clearing, 203 
inverting, 204 
reversing, 205 
?PLM 
Cmacro, 155, 168 
option, 21 
Pointer 
in Windows library, 20 
long, 20 
Pointing device See Mouse 
requirement 
Popup menu, 39 
POPUP statement, 37, 39-40 
PRELOAD keyword 
DIALOG resource statement, 41 
MENU resource statement, 37 
RCDATA resource statement, 33 
single-line resource statement, 31 
STRINGTABLE resource statement, 
34 
user-defined resource statement, 32 
printf function, 17 
ProcName parameter 
cBegin macro (Cmacro), 167 
cEnd macro (Cmacro), 167 
cProc macro (Cmacro), 163 
Program 
assembly-language, maintained with 
make, 141 
batch-processing, 141 
cl, 3, 11, 14 
cmacros, 3 
Dialog Editor See Dialog Editor 
DOS, 17 
DOS Tools See specific tool 
Font Editor See Font Editor 
Heapwalker, 3, 241 
high-level language, maintained with 
make, 141 
Icon Editor See Icon Editor 
# include, 12 
link4, 3, 14, 16, 85 
make See make 
mapsym, 96-97 
masm, 3, 11 
Pascal, 3 
rc, 3, 9, 25, 233 
resource compiler, 233 
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Program (continued) 
Shaker See Shaker 
source file, 9 
symdeb, 3, 15 
See also symdeb program 
use, 1] 
Windows, 3 
Program maintainer See make 
Program step command 
See p command 
Programming model, 12-13, 16, 21 
Prolog (Windows), 14, 19, 21 
Public symbol, 98 
Push button 
control, 51 
dialog-box control, 220 
PUSHBUTTON statement, 47, 51-52 


q (quit) command, 110, 112, 132 
quit (q command), 110, 112, 132 


r (register) command, 112, 132 

-r option (re command), 29 

R (read only) option (ba command), 
119 


Radio button 

control, 55 

dialog-box control, 220 
RADIOBUTTON statement, 47, 55-56 


Range command argument (symdeb), 
4 


Range parameter 
ec command, 121 
d command, 122 
da command, 122 
db command, 122 
dd command, 123 
dl command, 124 
ds command, 125 
dt command, 125 
dw command, 125 
f command, 128 
m command, 130 
s command, 133 
u command, 134 
v command, 134 
Raster font, 195 
Raw-data field (RCDATA resource 
statement), 33 
Raw-data resource, 31 
See also RCDATA resource 
statement 
re command, 11, 28-29 
re extension See Resource script file 
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re file See Resource script file 
re program, 3, 11, 25 
See also Resource compiler 
RCDATA resource, 33 
RCDATA resource statement, 25, 33 
rcinclude keyword, 28, 215, 233 
Record command argument (symdeb), 
114 
Record parameter 
| command, 130 
w command, 134 
Rectangle (dialog-box control), 220 
Redirect program input ({ command), 
112, 137 
Redirect program input and output 
(~ command), 112, 137 
Redirect program output 
} command), 112, 137 
Redirect symdeb input {< command), 
112, 137 
Redirect symdeb input and output 
(= command), 99, 101, 112, 137 
Redirect symdeb output 
(> command), 112, 137 
Redirecting input, 99 
Redirecting output, 99, 100 
Redirection (=) command, 99, 101, 112, 
137 
Refresh command (Font Editor) 
198-199 
Register 
ds, 19, 249-251 
r command, 112, 132 
ss, 19, 249-251 
symdeb argument, 114-115 
Register command argument (symdeb), 
114-115 
Register parameter As command), 132 
Reglist parameter, Save macro 
(Cmacro), 169 
Remote terminal 
debugging, 98 
setting up, 99 
Rename Dialog command, 232 
Replication parameter (Cmacro), 161 
Reporting level (memory allocation), 
setting, 100 
Tes a (Dialog Editor) See resource 
e 


RESIDENTNAME keyword 
(EXPORTS pte, 83 
Res-option field oe S 
statement), 83 
Resource 
adding, 11 
bitmap, 181 
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Resource (continued) 
compiling, 25, 28 
creating, 11, 25, 181 
cursor, 181 
defining, 11 
dialog box, 215 
directive, 26, 27 
file, 25, 215, 231, 233 
font file, 195 
icon, 181 
listing, 11 
naming, 26-29 
raw data, definition, 33 
re command, 11, 28-29 
script file, 11, 25-26, 27, 215 
compiling, 11 
creating, 11 
directive, 27 
source file, 11 
statement, 25 
string, definition, 32 
Resource compiler (rc), 3, 11, 25, 215 
Resource directive, 26, 27 
Resource file, 25, 215, 231, 233 
Resource Properties command (Dialog 
Editor), 226 
Resource script file 
compiling, 11, 27 
creating, 11, 25 
Dialog Editor, 233 
directive, 27 
# include directive, 27 
naming a resource, 26-29 
re extension, 25 
rcinclude keyword, 28, 215, 233 
resource statement, 25 
Resource statement 
ACCELERATORS, 25, 35 
acctablename field, 35 
CONTROL option, 36 
CURSOR, 25, 30 
event field, 35 
idvalue field, 36 
NOINVERT option, 36 
SHIFT option, 36 
type field, 36 
DIALOG, 25, 40 
dialog control statement, 47-65 
dialog option statement, 43 
height field, 41 a 
load-option field, 41 
mem-option field, 41 
namelD field, 41 
width field, 41 
x field, 41 
y field, 41 


Resource statement (continued) 
directive, 25 
listing, 25 
MENU, 36-40 
MENUITEM SEPARATOR 
statement, 40 
MENUITEM statement, 37, 38-39 
POPUP statement, 37, 39-40 
multiple-line, 25 
RCDATA, 25, 31 
resource, 30 
resource script file, 25 
single-line, 25, 30 
STRINGTABLE, 25, 34 
user-defined, 32 
user-defined resource, 25 
Resource-type field (single-line resource 
statement), 30 
Restore Dialog command, 232 
Restore output (symdeb) See SCROLL 
LOCK ke 
Result field (MENUITEM statement), 
38 


Roman font (Font Editor), 210 
Routine 

assembly-language, 17 

startup, 16 
Row command (Font Editor), 206 
Row menu (Font Editor), 200-201 
RTEXT statement, 47-48 
Run-time function (C language), 17, 

19-20, 249-251 

Run-time library, 16, 17, 22 


s (search) command, 112, 133 
s& command, 109, 112, 133 
s+ command, 109, 112, 133 
s— command, 132-133 
/s option (make), 144 
ave As command 
Dialog Editor, 235 
Font Editor, 198, 211 
Icon Editor, 190 
Save As dialog box (Font Editor), 211 
Save command 
Dialog Editor, 235 
Font Editor, 198, 211 
Heapwalker, 243 
Icon Editor, 190 
Saving 
See also Save As command; Save 
command 
character changes, 206 
dialog-box changes, 235 
font file, 211 
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sBegin macro (Cmacro), 158 
SBS_ BOTTO IGN, 64 
SBS_ HORZ, 64 
SBS_ LEFTALIGN, 64 
SBS_ RIGHTALIGN, 64 
SBS_ SIZEBOX, 65 
SBS_ SIZEBOXBOTTOMRIGHTALIGN, 
65 
SBS_ SIZEBOXTOPLEFTALIGN, 65 
SBS_ TOPALIGN, 64 
SBS_ VERT, 64 
Screen color, 185 
Script file, 11, 25-26, 27, 215 
See also Resource script file 
Script font (Font Editor), 210 
Scroll bar 
dialog box (Dialog Editor), 220 
horizontal, 45 
vertical, 45 
with a dialog box, 226 
SCROLL LOCK key (restore /suspend 
output}, 103 
SCROLLB 
class, control style, 64 
control class, 60 
control styles, 64-65 
/se See /segments option 
Search (s command), 112, 133 
Secondary monitor, setting up, 99 
Segment, 157 
Segment-address field 
dg command, 123 
memory-allocation message 
(symdeb), 107 
Segment-attributes field 
CODE statement, 78 
DATA statement, 79 
SEGMENTS statement, 81 
Segment macro (Omacro), 156 
Segment-name field, memory-allocation 
message (symdeb), 107 
Segment names, specifying, 15 
Segment:offset address argument 
(symdeb), 116 
Segment parameter, FarPtr macro 
(Cmacro), 171 
Segment-type field (dg command), 123 
Segmentation Test command 
ove desert} 242 
Segmentname field (SEGMENTS 
statement), 81 
Segmentname parameter, symbol 
specification (x? command), 135 
segments option, 87 


SEGMENTS statement, 81 
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SegName parameter 
assumes macro (Cmacro), 159 
createSeg macro (Cmacro), 157 
sBegin macro (Cmacro), 158 
sEnd macro (Cmacro), 158 
SegNameOFFSET (Cmacro), 160 
SegReg parameter, assumes macro 
(Cmacro), 159 
Select All command (Icon Editor), 191 
Select command (Icon Editor), 191 
sEnd macro (Omacro), 158 
Serial port, 98, 99 
Set address breakpoint (ba command), 
110, 119 
Set breakpoint (bp command), 108, 
111, 12 
Set breakpoint address (ba command), 
110, 119 
Set machine and source debugging 
(s& command), 109, 112, 133 
Set machine debugging only 
(s— command), 112, 133 
Set name (n command), 112, 131 
Set source debugging only 
(s+ command), 109, 112, 133 
Set source mode command See s& 
command; s- command; s+ 
command 
Set symbol value (z command), 112, 
136 
_setargv function, 16 
_setenvp function, 16 
Setting a virtual breakpoint, 108 
Shake menu (Shaker), 240 
Shaker 
application, 239 
commands, 239 
described, 3 
overview, 239 
Parameter menu 
Allocation granularity command, 
239 
Max objects command, 240 
Time interval command, 239 
Shake menu, 240 
State menu, 240 
starting, 239 
window, 239 
Shaker.exe file, 239 
Shell escape (! command), 112, 137 
SHIFT option (ACCELERATORS), 36 
Show Bits command her Bas 242 
Show command (Heapwalker), 24 
Single-line resource statement, 25, 30, 
dl 


Size box, 44, 65 
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Size box (continued) 
control, 60 
with dialog box, 226 
Size command (Font Editor), 207-208 
Size command (Heapwalker), 242 
Size dialog box (Font Editor), 208 
Size field 
dg command, 123 
dh command, 124 
Size parameter 
alignment option, 86 
a command, 119 
localX macro (Cmacro), 166 
/stack option, 87 
Size window 
described, 217 
Dialog Editor, 217, 218 
/(slash), use in rcinclude keyword, 28 
Small model 
application, 12, 16 
callback function, 13 
description, 12 
use, 12 
Solid command (Font Editor), 203 
Sort menu (Heapwalker), 242 
Source file, 11, 14 
Source-line display command See dot 
.) command 
Special-definition macro (Cmacro), 170 
SS register, 19, 249-251 
SS.. BLACKFRAME, 63 
SS. BLACKRECT, 63 
SS_ CENTER, 50, 63 
SS..GRAYFRAME, 63 
SS. GRAYRECT, 63 
SS_ ICON, 58, 63 
SS_ LEFT, 48, 63 
SS..RIGHT, 48, 63 
SS_. USERITEM, 63 
9S. WHITEFRAME, 63 
S5_ WHITERECT, 63 
/st See /stack option 
Stack, 15 
Stack-checking option (Cmacro), 156 
/stack option, 87 
Stack probe, definition, 15 
Stack size, recommended minimum, 74 
STACKSIZE statement, 75, 77-78 
Standard style 
changing, 224 
dialog-box control, 223-224, 226 
Standard Styles command (Dialog 
Fiditor), 223, 224, 226, 229-231 
Start application See go (g command) 
Start command (Shaker), 240 


Startaddress parameter 
g command, 128 
p command, 132 
t command, 133 
Starting 
debugging, 100 
Dialog Editor, 216 
Font Editor, 195 
Heapwalker, 241 
Icon Editor, 181 
make, 143 
Shaker, 239 
symdeb, 100-104 
Starting application 
See g command 
Starting point See Entry point 
Startup command option, 101 
Startup routine, 16 
State menu (Shaker), 240 
Statement 
ACCELERATORS, 25, 35 
BITMAP, 25, 30 
CAPTION, 43, 45 
CHECKBOX, 47, 50 


T 
DEFPUSHBUTTON, 47, 54 
DESCRIPTION, 77 
DIALOG, 25, 40 
EDITTEXT, 47, 56 
EXPORTS, a 72, 82 
FONT, 25 
GROUPBOX. 47, 53 
HEAPSIZE, 77 
ICON, 25, 30, 47, 57 
IMPORTS, 83 
LIBRARY, 74, 76 
LISTBOX, 47, 52 
LTEXT, 47 
MENU, 36-40, 43, 46 
MENUITEM, '37, 38 
MENUITEM SEPARATOR, 40 
NAME, 73, 75 
POPUP, a7. 39 
PUSHBUTTON, 47, 51 
RADIOBUTTON, 47, 55 
RCDATA, 25, 31 
resource, 20 
resource script files, 25 
RTEXT, 47, 49 
SEGMENTS, 81 
STACKSIZE, 1044 
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Statement (continued) 


STYLE, 41, 43 
STATIC 
class, control style, 59 
control class, 57 
control style, 63 
Static-memory storage 
private, 160 
public, 161 
Static variable, 20, 108 
StaticX (Cmacro), 160 
Step command (Shaker), 240 
Sticky breakpoints, 121 
Stop command (Shaker), 240 
Storage, static-memory 
private, 160 
public, 161 
Storage-allocation macro (Omacro), 160 
Strikeout font (Font Editor), 210 
String-definitions field 
(STRINGTABLE resource 
statement), 34 
String resource, 34 
See also RCDATA resource; 
STRINGTABLE resource; 
STRINGTABLE resource 
statement 
STRINGTABLE resource, 34 
STRINGTABLE resource statement, 
25, 34 
Structure, packed, 15 
STUB statement, 84 


Style 

BUTTON class, 50, 53, 54, 55 

default 
CHECKBOX statement, 51 
CTEXT statement, 50 
DEFPUSHBUTTON statement, 55 
EDITTEXT statement, 57 
GROUPBOX statement, 54 
ICON statement, 58 
LISTBOX statement, 53 
LTEXT statement, 48 
PUSHBUTTON statement, 52 
RADIOBUTTON statement, 56 
RTEXT statement, 49 

DS_ ABSALIGN, 41, 42 

DS. SYSMODAL, 43 

EDIT class, 57, 61-62 

global window, 224 

LISTBOX class, 52, 63-64 

STATIC class, 57, 63 

window 
global, 224 
listing, 44-45 
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Style (continued) 
window (continued) 
WS_ BORDER, 48, 53 
WS. CHILD, 42 
WS_ DISABLED, 52, 54-57 
WS... GROUP, 48-52, 55-57 
WS_ HSCROLL, 57 
WS_POPUP, 43 
WS_SYSMENU, 43 
WS... TABSTOP, 48-52, 54-57 
WS_ VSCROLL, 53, 57 
Style field 
CHECKBOX statement, 51 
CONTROL statement, 58 
CTEXT statement, 50 
DEFPUSHBUTTON statement, 55 
EDITTEXT statement, 57 
GROUPBOX statement, 54 
ICON statement, 58 
LISTBOX statement, 52 
LTEXT statement, 48 
PUSHBUTTON statement, 52 
RADIOBUTTON statement, 56 
RTEXT statement, 48 
STYLE statement, 43 
STYLE statement, 43 
# include directive, use of, 43 
style field, 43 
syntax, 43 
window style, listing, 44-45 
Styles menu (Dialog Editor), 216, 221, 
223-224 296, 299-231 
Suspend output (symdeb) See SCROLL 
LOCK key 
Swiss font (Font Editor), 210 
Symbol 
absolute (_ — acrtused), 22 
public, 98 
Symbol command argument (symdeb), 


115 | 

Symbol file, 96-98, 102-103 
application, 102 
assembly-language application, 98 
C-language application, 97-98 
debugging, 96-97 
library, 102 
naming, 102 
Pascal application, 94 
recommended, 102 
setting up, 96 
symbol map, 104 

Symbol map, 104-106 
data segment, instance number, 105 
displaying symbols, 106 
listing, 104 
open, displaying, 105 
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Symbol map (continued) 
opening, 105 
symdeb, 104 
Symbol map (open) See Examine 
symbol (x? command) 
Symbol parameter 
xo command, 135-136 
z command, 136 
Symbol redefinition (Cmacro), 174 
Symbol specification, 135 
Symbolfiles parameter, 100 
Symbolname parameter, symbol 
specification (x? command), 135 
symdeb 
address argument, listing, 116-119 
command, 100 
See also symdeb commands 
command argument, listing, 114-115 
described, 3 
displaying open symbol map, 105 
expression, 117-118 
fatal exit, 110 
flag name, listing, 115 
flag register, 115 
key, 103, 104 
opening a symbol map, 105-106 
operator, 117 
option designator, 102 
option listing, 100-102 
starting, 100 
symbol examining, 104 
symbol map, 104 
variable displaying, 108-109 
symdeb address 
argument listing, 116 
argument syntax, 116 
symdeb command, 100, 101 
See also symdeb commands 
symdeb commands 
* (comment), 112, 138 
? (compute and display expression), 
112, 136 
{ (redirect program input), 112, 137 
redirect program input an 
output), 112, 137 
} (redirect program output), 112, 137 
< (redirect symdeb input), 112, 137 
= (redirect symdeb input and 
output), 99, 101, 112, 137 
> (redirect symdeb output), 112, 
137 


! (shell escape), 112, 137 

. (view source lines), 112, 136 

a (assemble), 110, 118 

ba (breakpoint address), 110, 119 
be (breakpoint clear), 110, 120, 121 


symdeb commands (continued) 
bd Us disable), 111, 120, 


be (reac enable), 111, 120 

(breakpoint list), 111, 121 

bot (breakpoint i 108, 111, 121 

c (compare), 111, 121 

d (display static variable), 108 

d {dump memory using previous 
type), 111, 122 
a (dump memory ASCII), 111, 122 

db dump memory pe) 111, 129 

dd (dump memory doub e-words), 
111, 123 

dg display global heap), 111, 123 

dh (display local Keapl 111, 124 

dl (dump memory, long floating 

point), 111, 124 

dq (dump task queue), 111, 124 

ds (dump memory, short floating 
point), 111, 125 

dt (dump memory, ten-byte reals), 
111, 125 

dw (dump memory words), 111, 125 

e (enter), 111, 125-126 

ea (enter address), 111, 126 

eb (enter Pa, 111, 126 

7 enter doub e-words), 111, 126 

gees long floating point), 111, 


es (enter short floating point), 111, 


et ee ten-byte reals), 111, 127 

ew (enter words), 111, 128 

f (so 111, 128 

g (go), 107, 111, 128 

h (add hexadecimal), 111, 129 

i (input from port), 111, 129 

k (backtrace stack), 111, 129 

kt (backtrace task , 110, 129-130 

I (load), 111, 130 

listing, 110-112 

m (define or execute macro), 112, 131 

m (move), 112, 130 

n (name), 112, 131 

o (output to port), 112, 131 

p (program step), 112, 132 

q (quit), 110, 112, 132 

r register), 112, 132 

s (search), 112, 133 

s& (set machine and source 
debugging), 109, 112, 133 

s— (set machine debugging only), 112, 
133 

s+ (set source debugging only), 109, 
112, 133 
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symdeb commands (continued 
t (trace program instruction), 112 
133 


u (display unassembled instructions), 
109, 112, 134 
v (view source lines), 109, 112, 134 
w (write to disk), 112, 134 
x (examine symbol map), 104, 106, 
112, 185 
x? (examine symbol), 106, 112, 135 
xo (open cei 105, 112, 135-136 
z (set symbol value), 112, 136 
symdeb program, 13, 95 
allocation message, 107-108 
breakpoint setting, 108 
command See symdeb commands; 
specific command 
incorrect file retrieval, prevention of, 


macro definition, 101 
memory-allocation message, 107 
opening symbol map, 105-106 
starting application, 107 
symdeb utility See symdeb program 
SYS ee key (interactive breakpoint), 


Soca cence allocation, 241 
System menu box, 44, 226 


t (trace program instruction) 
command, 112, 133 
Tab stop, 229 
Tab Stop Bit check box, 229-231 
Tab Stop button (Dialog Editor), 229 
.targetextension parameter, 148 
ma ee parameter (make description 
e}, 142 
Template, DIALOG, 40-41 
Terminal, 98-99 
Test mode (Dialog Editor), 217 
Testing, executable files, 95 
_ TEXT code segment, 15-16 
Text control 
centered, 49-50 
dialog box, 220 
left-justified, 47-48 
right-justified, 48-49 
Text editor 
creating 
make description file, 141 
resource script file, 25 
use, 1] 
Text field 
CHECKBOX statement, 50 
CONTROL statement, 58 
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Text field (continued) 
CTEXT statement, 49 
DEFPUSHBUTTON statement, 54 
DESCRIPTION statement, 77 
GROUPBOX statement, 53 
LTEXT statement, 47 
MENUITEM statement, 38 
POPUP statement, 39 
PUSHBUTTON statement, 51 
RADIOBUTTON statement, 55 
RTEXT statement, 48 
Time interval command (Shaker), 239 
Title bar, 44 
Tools 
Application Development, 3 
cel, 3, 11, 14 
emacros, 3 
noes Editor See Dialog Editor 
Font Editor See Font Editor 
Heapwalker See Heapwalker 
Icon Editor See Icon Editor 
# include, 12, 215 
link4, 11, 16, 18 
make, 3, 141 
mapsym, 96-97 
masm, 3, 11 
Pascal, 3, 95 
re, 3, i1, 25 
resource compiler, 3, 11, 25, 215, 233 
Shaker, 3, 239 
symdeb, 3, 15, 95-138 
use, 11 
Windows, 3 
tools.ini file ake program), 148 
Top= Bottom command (Font Editor), 
205 
Trace command See t command 
Trace program instruction or call 
command See p command 
Trace program instruction 
(t command), 112, 133 
TranslateAccelerator function, oo 
Type field (ACCELERATORS), 3 
TypelD field (user-defined ae 
statement), 32 


u (display unassembled instructions) 
command, 109, 112, 134 

U (read/write option (ba command), 
119 


Unary operator (symdeb), 117 
Unassemble command 

See u command 
# undef directive, 66-67 
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# undef resource directive, 25 

#: undef statement, 66 

Underline font (Font Editor), 210 
Undo command (Font Editor), 206 
Updating files, 141 

User-defined control window, 58 
User-defined resource, 32 

User-defined resource statement, 25, 32 
User library, symbol file, 102 

Utility See Program; Tools 


v (view source lines) command, 109, 
112, 134 
Value command argument (symdeb), 
15 


Value field (# define statement), 66 
Value parameter 
ba command, 119 
bp command, 121 
ed command, 126 
el command, 127 
es command, 127 
et command, 127 
ew command, 128 
i command, 129 
k command, 129 
kt command, 129-130 
macro definition (make), 145 
o command, 131 
Pp command, 132 
r command, 132 
t command, 133 . 
z command, 136 
Valuel parameter (h command), 129 
Value2 parameter (h command), 129 
Variable 
_—argce, 16 
—— argv, 16 
displaying, 108-109 
environ, 16 
environmental 
INCLUDE, 28, 66 
PATH, 84 
local, 20 
static, 20, 108 
Variable-pitch font, 207-208, 212 
Vector font, 195 
View command See v command 
View Dialog command (Dialog Editor), 
231 


View Include command (Dialog Editor), 
234-235 

View source lines (v command), 109, 
112, 134 

Visible bit, dialog box, 225 


Visible Bit check box, 225 


w (write te disk pone 112, 134 
(r option (symdeb), 100-101 
WORD seesed option ais 
bet 119 
Walk Heap command (Heapwalker), 
241 


Walk menu (Heapwalker), 241-242 
(narnep option (link4), 87 
orl 200 


ider command (Font 
206 


Width command (Font Editor), 
Width field 
CHECKBOX statement, 51 
CONTROL statement, 59 
CTEXT statement, 50 
DEFPUSHBUTTON statement, 55 
DIALOG resource statement, 41 
EDITTEXT statement, 57 
GROUPBOX statement, 54 
ICON statement, 58 
LISTBOX statement, 53 
LTEXT statement, 48 
PUSHBUTTON statement, 52 
RADIOBUTTON statement, 56 
RTEXT statement, 49 
Width menu (Font Editor), 200 
?WIN option (Cmacro), 19, 156 
Window 
application, Pascal-language, 11 
child, 43, 44, 
debugging applications, 95 
Dialog Editor, 216 
disabled, 45 
epilog, 14, 19, 21, 155 
fatal exit, 110 
Font Editor 
character, 197 
character viewing, 197 
font, 198 
main, 197 
function, 13 
Heapwalker, 241 
iconic, 44 
import library, 88 
kernel function, 19 
library, 16, 19-20, 22, 73 
linker, 11 
See also link4 
MS-DOS Executive, 110, 195, 216, 
239, 241 
overlapping, 45 
parent, 42 
pop-up, 43, 44, 45 
presentation manager, 25 
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Window (continued) 
prolog, 14, 19, 21, 155 
resource compiler (rc), 28, 215, 233 
Shaker, 239 
visible, ‘45 
Window border, 44 
Window style 
dialog box, 43 
listing, 44-45 
windows.h file, 11, 20, 43 
ear function, 13, 21, 108 


WM_ SYSCOMMAND message, 35 
Work mode (Dialog Editor), 217 
Write command See w command 
Write to disk (w command), 112, 134 
WS_ BORDER, 43, 44, 53, 57 

WS. CAPTION, 44 

WS. CHILD, 42, 44 

WS_ CHILDWINDOW, 45 

WS_. CLIPCHILDREN, 45 

WS. CLIPSIBLINGS, 45 

WS_ DISABLED, 45, 52, 54-57 
Ws_ DLGFRAME, 44 

WS. GROUP, 44, 48-52, 55-57 
Ws. HSCROLL, 45, 57 


44 
WS_ MAXIMIZEBOX, 44 

WS_ MINIMIZE, 44 

WS_ MINIMIZEBOX, 44 

WS_. OVERLAPPED, 44 

WS_ OVERLAPPEDWINDOW, 44 
WS_ POPUP, 43, 44 
WS_POPUPWINDOW, 45 
WS_SIZEBOX, 44 
WS_SYSMENU, 43, 44 

WS_ TABSTOP, 44, 48-52, 54-57 
WS_ VISIBLE, 45 
WS_VSCROLL, 45, 53, 57 


x (examine symbol map} command, 
104, 106, 112, 135 
/x option, 101 
x? (examine symbol) command, 106, 
112, 135 
X field 
CHECKBOX statement, 51 
CONTROL statement, 58 
CTEXT statement, 50 
DEFPUSHBUTTON statement, 55 
DIALOG resource statement, 41 
EDITTEXT statement, 57 
GROUPBOX statement, 54 
ICON statement, 58 
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X field (continued) 
LISTBOX statement, 52 
LTEXT statement, 48 
PUSHBUTTON statement, 52 
RADIOBUTTON statement, 56 
RTEXT statement, 49 
Size window (Dialog Editor), 217 

X parameter 
DefX macro (Cmacro), 170 
extermX macro (Cmacro), 162 
globalX macro (Cmacro), 161 
labelX macro (Cmacro}), 162 
localX macro {Cmacro}, 166 
parmX macro (Cmacro}, 164 
staticX macro (Cmacro), 160 

xo (open symbol map) command, 105, 

112, 135-136 


Y field 
CHECKBOX statement, 51 

~ CONTROL statement, 58 
CTEXT statement, 50 
DEFPUSHBUTTON statement, 55 | 
DIALOG resource statement, 41 
EDITTEXT statement, 57 
GROUPBOX statement, 54 
ICON statement, 58 
LISTBOX statement, 52 
LTEXT statement, 48 
PUSHBUTTON statement, 52 
RADIOBUTTON statement, 56 
RTEXT statement, 49 
Size window (Dialog Editor), 217 


z (set symbol value) command, 112, 136 
—Zd option, 15, 97 
—Zp option, 15 
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Introduction 


The Microsofte Windows presentation manager is designed to be an inter- 
face that makes it easier to use a computer. To fulfill this design, Windows 
applications should provide a friendly user interface that is consistent with 
other Windows applications so that the user does not have to relearn basic 
concepts. 


This style guide provides suggestions on how to design a consistent user 
interface for Windows applications. ‘These are reasonable guidelines, 
intended to encourage a common user interface for all Windows applica- 
tions, to benefit the user. Applications that employ these guidelines are 
easier to learn and use. 


This guide does not cover all possible user-interface issues. Applications 
that have needs not covered by this guide should develop logical exten- 
sions of these guidelines. Applications should deviate from the guidelines 
only when absolutely necessary. 


The Microsoft Windows presentation manager runs with the MS-DOSe 
operating system. MS-DOS may also be known as DOS or PC-DOS. In this 
style guide, MS-DOS will be referred to as DOS. 


Key combinations and sequences are referred to in a particular style in this 
guide. A plus sign (+) between two keynames indicates that those keys 
must be pressed at the same time. For example, “Press ALT+ESCAPE” 
means that users should press and hold down the ALT key while they press 
and release the ESCAPE key. A comma between two keynames indicates 
that those keys must be pressed sequentially. For example, “Press ALT, 
SPACEBAR” means that users should press and release the ALT key, then 
press and release the SPACEBAR. 


S wae 


Chapter 1 
Main Window 


1.1 
1.2 
1.3 
1.4 
L.o 
1.6 


Introduction 9 
Icons 6 
Window Captions 
Output 7 
Scrolling 8 
Split Windows 
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Main Window 


1.1 Introduction 


Every application developed for Microsoft Windows should have at least 
one window to serve as the main visual interface for all user interaction 
with the application. This main window should be an overlapping window 
with a title bar, Control menu, Minimize and Maximize boxes, and a win- 
dow border. (Applications that are fixed in size, however, should not have 
a window border or a Maximize box.) A menu bar is recommended if the 
application has commands. Scroll bars are recommended if the application 
contains more information than can fit in a window. The following screen 
shows the recommended format of the main window and its components: 


Control- menu box Maximize box 


Control menu | Title bar Menu bar Minimize box 


; i 
CHU chia aracter Paragraph 
a 6Move Alt+k? 
Size Alt+F8 
Minimize Alt+F9 
Maximize Alt+F18 


Alt+Fh 


scro11 bar 


Window border Scroll bar 


Figure 1.1 Main Window 


The application should create and display the main window as its first 


task to let the user know the application is running. It should destroy the 
main window as its last task. 
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1.2 Icons 


Every application should have an icon that uniquely identifies the applica- 
tion. Windows uses the icon to symbolize the loaded application when that 
application’s main window is shrunk and not visible. 


An icon can be designed and added to an application’s executable file as a 
resource. The application registers the icon with Windows when the main 
window is created. 


When an application is reduced to an icon, it should hide all its associated 
dialog boxes and child windows. If an application is unable to hide its dia- 
log box (because user input is required), then the application should cause 
a warning beep to sound. When a window is restored from an icon, it is the 
application’s responsibility to display any dialog boxes or child windows 
previously displayed. 


An application can also choose to draw the icon while the application is 
running. This permits an application to continue to display some output 
even though its main window is not visible. This type of output is limited 
to the space occupied by the icon. The application must be prepared to 
update the icon when required. An example is Clock, which continues to 
display the correct time when it is reduced to an icon, shown as follows: 


Figure 1.2 Clock Icon 


1.3 Window Captions 


To identify an application’s window, every application should place a 
unique caption in the title bar of its main window. At a minimum, the 
caption should contain the application’s name, with the first letter capital- 
ized. Additional text may be added. 


If an application’s window content is always associated with a specific 
data file, the application should add the name of the data file to the cap- 
tion in the title bar, separating the application name from the filename 
with a hyphen. The filename should appear in uppercase letters and should 
ear the filename extension (if any). The file’s pathname should not be 
included. 


por 


Main Window 


The following screen shows the recommended format for the title-bar cap- 
tion of the main window: 


Murphy & Allen, Realtors +f 
11958 165h Ave. E., Seattle, WR 98412 a: 


PREPARING @ HOHE FOR SALE 


You can understand that showing a hame to its best advantage makes 
the buyer want to purchase quickly and at a better price. Here are 
some tested tips to set the stage for profitable and early sale. 


Lai Nah ee ee ee 


Figure 1.3 Window Caption with Filename 


If there is no current file, the string “(Untitled)” should be used, as shown 
in the following example: 


Paint - (Untitled) 


1.4 Output 


Applications should display all output, except error messages, warnings, 
and prompts for additional command information, in the client area of the 
application’s windows. The client area is the rectangle bounded by the 
menu bar on the top, the scroll bars, if any, on the right side and bottom, 
and the window border on the left side. The client area is the area the user 
has access to. Output can be text, graphics, or both. The application must 
decide the format and draw the actual display. Applications that need to 
display a complete image (for example, the complete face of a clock) 
should adjust the image to fit in the available space. 


Since client-area size and shape can vary, an application can adjust its 
display to either resize or clip the image. When an image is clipped, any 
part of the output that extends beyond the client area is not displayed. 
Applications that clip output should provide a method of scrolling the out- 
put in the window (see Section 1.5). An application must not display any 
of its output in another application’s window. 


Applications must be prepared to update the display when requested to by 
Windows. 
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The following screen shows two applications with output in their windows: 


Clipped output Client area 


: = te Rh eS Rei 
sp file Edit Search Character Parp 


Murphy & Rllen § 
11958 165h Ave. E., Seatte 


PREPARING A HOME FOR SALE 


You can understand that showing a hq - 
the buyer want to purchase quickly §f 
some tested tips to set the stage f 


Fix up inside. Badly faded walls 14. 
add a fresh look. Clean windows shg 


Make minor repairs. Dripping fauce§ 
plumbing is in good working conditi¢ 
anything about the neighbors, don'té 
idea to really clean up the front lg 


Scroll bar 


Figure 1.4 Output in Windows 


1.5 Scrolling 


Applications should provide scrolling for a window’s client area whenever 
the output is too large to display all at once. For example, a window 
whose output is the contents of a data file can display a portion of the file 
at a time and let the user scroll the contents of the file as desired. 


Applications that scroll should provide ways for scrolling with both the 
keyboard and the mouse (or other pointing device). 


For scrolling with the keyboard, applications should use the following 
recommended keys: 


Main Window 


Key Action 

PAGE UP scrolls up one screen. 
PAGE DOWN Scrolls down one screen. 
CONTROL-+-PAGE UP Scrolls left one screen. 


CONTROL-+PAGE DOWN Scrolls right one screen. 


For scrolling with the mouse, the application should include a horizontal 
or vertical scroll bar with the window (it should use both if it permits 


scrolling in all four direction 


s). Scroll arrows at either end of the scroll bar 


indicate the direction of scrolling. The rectangular scroll box moves within 
the scroll bar to indicate the position of the displayed data in the file. The 
following screen shows the placement of scroll boxes and scroll arrows: 


hae arin Arar nnn PLR AP SRR AAA OPP A UO ON POC PEE Pee 


we Ey, TTR IRA AS ASA ASA rr 


Scroll box 
Up scroll arrow 


A File Edit Search Character Paragraph Document 


xX 


I 


Scroll box 


She i % 


Right scroll arrow 


Left scroll arrow Down scroll arrou 


Figure 1.5 Scroll Boxes and Scroll Arrows 


The application should respond to user input as follows: 


Mouse Movement 


Click the up scroll arrow 
Click the down scroll arrow 
Click the left scroll arrow 


Click the right scroll arrow 


Action 


Scrolls up one unit. 
Scrolls down one unit. 
Scrolls left one unit. 


Scrolls right one unit. 
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Click the area above or below Scrolls up or down one screen. 
the scroll box in the vertical 
scroll bar 


Click the area to the left or right Scrolls left or right one screen. 
of the scroll box in the horizontal 
scroll bar 


Drag the scroll box Scrolls to the approximate location 


in the file as shown on bar. 


1.6 Split Windows 


Applications can split the client area of a window into separate viewing 
areas by creating child windows in the client area. A split window permits 
different types of output within the same main window. An example might 
be a spread-sheet application, in which the user needs to see different areas 
of the data simultaneously. 


Applications that split windows in this way are responsible for maintain- 
ing each individual window. A child window must reside within the client 
area of its parent window. Child windows do not usually have icons to 
represent them. 


The following screen shows a split window: 
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Child window Client area of parent window 


Ie Cpe RA ATG hn OA RRL TI AAAS Wein, ANA RNS aa RAR AA ARAMA CR AKA AARC a sR ACARI RAO Lee cece Tu 


File Edit Select format Options [Calculate ss ss t= Help f 
[25 | SE | 
ee ee ee ee al 


Figure 1.6 Split Window with Two Child Windows 


Main Window 


The common use of split windows is also a characteristic of the multiple- 
document interface provided by Windows. The multiple-document inter- 
face supports the viewing of multiple windows within one application— 
either different views of the same data, or different documents or sets of 
data. An application that uses the multiple-document interface can con- 
tain document windows cehid windows within the main window) and sub- 
divisions of windows (child windows within a document window). For more 
information, see Chapter 13, “Multiple-Document Interface.” 
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Menus 


2.1 Introduction 


Applications developed for Microsoft Windows that have commands 
should provide menus to give the user access to the commands. A menu 
is a list of items, such as commands, from which the user chooses. Each 
menu is represented by a name in the menu bar of the application’s main 
window. The list of items is displayed when the user selects the corre- 
sponding menu name by using the keyboard or the mouse. 


2.2 Menu Names 


Every menu must have a menu name. The menu name represents the com- 
plete menu, so it should always state as clearly as possible the purpose 

of the items in the menu. Compound names may be used (for example, 
Fontsize). Numbers should not be used in the menu bar, but are accept- 
able for use with menu items in drop-down menus. Menu names should not 
be padded with spaces. 


To give keyboard users direct access to menus, menu names that use mne- 
monics are recommended. A mnemonic is a unique character in the menu 
name that allows the user to select the menu by first pressing the ALT key, 
then pressing the key that corresponds to the character. Mnemonics 
should be, in order of preference, the first letter of the menu name, a con- 
sonant in the name, or a letter in the name. Applications that use a non- 
Latin alphabet (for example, Kanji) and operate on a standard keyboard, 
such as an IBM-PC keyboard, may use a Latin alphabet character prefix. 
Underlining indicates the mnemonic character. 


The following screen shows a list of menu names in the menu bar: 


Menu bar Hnemonic 


wana ROE ARNE POP de BSE RP AAT BARNS RRP RCRD 7 


| Menu names 


Figure 2.1 Menu Names 
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2.3 Menu-Item Names 


Menu-item names should specify the action the user will initiate by choos- 
ing them. Item names should be unique within a menu, but applications 
may use the same item name in different menus to represent different 
actions. Compound names may be used. Mnemonics should be used both 
on the menu bar and for menu items in a drop-down menu. If numbers are 
used as mnemonics in menu items, the format of the items should be num- 
ber, space, then command text. Unlike menus, menu items can be chosen 
by pressing just the mnemonic key. 


In general, items that have similar functions should be placed together. 
Items that are clearly different should be separated from other items with 
a line separator. Menu-item names should not be placed in the menu bar. 
Only menu names should be included in the menu bar. The following 
figure shows a sample listing of menu items: 


Normal 


Bold 
Italic 
Underline 
Superscript 
Subscript 


“1 Modern 
2 Tms Ran 
3a Helv 


Figure 2.2 Items in a Menu 


2.4 Menu-Item Types 


Menu items are of several types. They may cause a specific command to 
be carried out, or they may allow the user to choose from among several 
features. A menu item may also give the user the option to turn a certain 
feature on or off (a toggle command). Some menu items request additional 
information from the user by generating a dialog box. 
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Menu items include the following: 


Item Description 

Command Carries out actions, such as opening or deleting 
: a file. 

State setter Sets some system state. For example, these may 


be used to turn a feature on or off (a toggle com- 
mand) or to choose from several features. 


Extended command Causes a dialog box to appear before the com- 
mand is carried out. The user then is required to 
supply additional information, make additional 
choices, or cancel the request. 


The following figure shows several types of menu items: 


Zoom In c d 


VNo Grid 
Eine Grid 
Medium Grid State setters 
Coarse Grid 


Edit Pattern... eH Extended command 


VFor Printer 
For Screen 


Figure 2.3 Types of Menu Items 


2.4.1 Toggle Commands 


Applications should always show whether the system state implied by a 
toggle command is active or not. If the command is active, the application 
should place a checkmark next to the command name. Otherwise, no 
checkmark should appear. 


Menus may contain any number of toggle commands. Toggle commands 
are of two basic types: independent and mutually exclusive. If toggle com- 
mands are independent, they may be on or off regardless of the state of 
other commands. Mutually exclusive toggle commands will, when acti- 
vated, deactivate associated toggle commands. 


Toggle commands that affect the same command should be placed to- 


gether and should be separated from other commands with a line separa- 
tor. If many toggle commands are in one group, at least one command 
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should turn off all commands in that group. If two or more toggle com- 
mands are mutually exclusive, the application must make sure that the 
commands cannot be checkmarked at the same time. Mutually exclusive 
commands should be separated from other menu commands by a line 
separator. 


The following figure shows two groups of mutually exclusive toggle com- 
mands with checkmarks that indicate which commands are active: 


Bold 
Italic 
Underline 
Qutline 
Strikeout 


“Left flligned 
Centered 
Right Aligned 


Figure 2.4 Mutually Exclusive Toggle Commands 


2.4.2 Menu Items That Use Dialog Boxes 


Menu items that require additional information before they can carry out 
their actions should prompt the user for the information by displaying a 
dialog box. The dialog box requires action by the user before the applica- 
tion can continue. The menu-item name should end with an ellipsis (...) 
and the item, when chosen, should display the dialog box. 


For more information on dialog boxes, see Chapter 8, “Dialog Boxes.” 


2.5 Disabled Menu Items 


The application must determine when the use of a menu item is appropri- 
ate. When the use of an item is not appropriate, the application must dis- 
able the item and gray the menu-item name. A grayed item lets the user 
know the item is disabled. Graying an item is only an indicator, and if the 
item is not specifically disabled, the user can still choose it. When this 
happens, a message is sent to the application. It is up to the application to 
determine how best to respond to the user action. 


The following figure shows grayed menu items: 
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fait Sia fhe Bel 
Pany Dirde las 
Paste Shift+Ins 
oe Gar Ded 


Select All | 
| Time/Date F5 


Figure 2.5 Grayed Menu Items 


2.6 The Control Menu 


The Control menu is predefined by Microsoft Windows. Therefore, the list 
of menu items, the order in which they appear, and their functions are, for 
the most part, preset and cannot be changed. Two exceptions are the 
Close command, which may be removed from the Control menu, and the 
About... command, which may be appended to the Control menu if there is 
no other logical place to locate it. (Otherwise, About... is added to the first 
menu in the application’s menu bar. See Section 2.10 for more information 
on the About... command.) The following figure shows the Control menu: 


Restere  8ie«b 
Hove Alt+F? 
$ize Alt+F8 
Minimize Alt+F9 
Maximize Alt+F18 


Close Alt+F4 


Figure 2.6 Control Menu 


2.6.1 Disabled Control-Menu Items 


When an application is not using items in the Control menu, the items 
should be grayed. For example, an application may not allow its window 
to change sizes. When this application is running, the Size command listed 
in the Control menu should be grayed. 
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2.6.2 The Close Command 


The Close command is the last command on the Control menu for all! win- 
dows, including dialog boxes and child windows, unless an About... com- 
mand is appended to the menu. The Close command is defined to mean 
“close the window.” In the case of the parent window of the application, it 
may be interpreted to mean “end the application.” Double-clicking the 
Control-menu box with the mouse is an accelerator for Close. However, 
the recommended way for an application to quit is through the use of the 
Exit command appended at the bottom of its first drop-down menu. (See 
Section 2.9 for more information on the Exit command.) If any window 
within the application should always remain open, the Close command 
may be removed from the window’s Control menu. 


If the user chooses the Close command from the Control menu after mak- 
ing changes without saving them, the application should display a dialog 
box warning of data loss. For more information on dialog boxes and warn- 
ings, see Chapter 8, “Dialog Boxes.” 


2.7 The File Menu 


Every application that works with data files should have a File menu. The 
File menu should provide all commands needed to open and create files 
and to save data in files. The File menu should be the first menu listed in 
the menu bar. 


It is recommended that the File menu contain the following commands 
and that they have the following actions: 


Command Action 


New | Deletes all existing data, removes the current filename 
from the title bar, and starts the application at its 
beginning. If choosing this command could destroy 
existing data, the command should generate a dialog 
box asking the user to verify the action before it is 
carried out. The letter “N” is the recommended 
‘mnemonic. 


Open... Prompts the user for the name of the file to be opened, 
then opens it and uses the file as the current file. The 
letter “O” is the recommended mnemonic. 


Save Saves the existing data in the current file. If the file is 
untitled, the application should generate a Save As... 
dialog box. The letter “S” is the recommended mne- 
monic. 
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Save As... Prompts the user for the name of a file to save the 
current data in, then opens the file and copies data to 
it. The letter “A” is the recommended mnemonic for 
the Save As... command. 


The following figure shows the recommended format for the File menu: 


New | 
Open... 


Save 
Save As... 


Figure 2.7 File Menu 


Menu items that prompt for user input should use application-modal dia- 
log boxes. For more information on dialog boxes, see Chapter 8, “Dialog 
Boxes.” 


Note 


In all cases, applications should take the safe approach when carrying 
out default actions with files; that is, they should always attempt to 
prevent the loss of data from existing files. 


2.4.1 The New and Open... Commands 


If the user chooses the New or Open... command (or the Close command 
from the Control menu) after making changes without saving them in a 
file, the application should display a dialog box with the following format: 


Save current changes: (untitled) 


Figure 2.8 Dialog Box with Warning 


The application should use the appropriate description of the data file in 
the first line of the message (in the preceding figure, the date file is unti- 
tled). The Yes button is the default button. 
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2.7.2 The Save Command 


The Save command should overwrite the existing file without asking per- 
mission; however, if there is no current filename, the application should 
carry out a Save As... command instead. 


2.7.3 The Save As... Command 


The Save As... command should display a dialog box with the following 
format: | 


C= \WINDOWS 


Figure 2.9 Save As... Dialog Box 


The Save As... dialog box should propose the existing filename as the 
default. If there is no existing filename, it should propose a reasonable 
default. The OK button is the default button. 


If choosing the Save As... command would overwrite an existing file, the 
command should always display a dialog box to ask permission to over- 
write, as shown in the following example: — 


Notepad | 


W/ Replace existing ABC .TRT 


Perr rer 


Figure 2.10 Save As... Dialog Box with Warning 


If the user selects the No button, the application should return to the Save 


As... dialog box. Otherwise, the application should attempt to save the 
file. The No button is the default button. 
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2.8 The Edit Menu 


Every application that lets the user move or copy text or graphics by using 
Clipboard should have an Edit menu. The Edit menu should provide all 
the commands needed to carry out Clipboard operations. 


The Edit menu should contain at least the following commands: 


Command 


Undo 


Cut 


Copy 


Paste 


Clear 


Action 


At a minimum, reverses the action of the most 
recently chosen Edit-menu command. You may want 
to add more information to this command and expand 
its function. The letter “U” is the recommended mne- 
monic. 


Copies the selection to the Clipboard, then deletes the 
selection. The letter “t” 1s the reeommended mne- 
monic. 


Copies the selection to the Clipboard without deleting 
the selection. The letter “C” is the reeommended mne- 
monic. 


Copies the contents of the Clipboard to the applica- 
tion’s data file. The letter “P” is the recommended 
mnemonic. 


Deletes the selection, but leaves the Clipboard 
unchanged. The letter “l” is the recommended 
mnemonic. 


Commands that require a selection should create a selection through the 
techniques described in Chapter 4, “Selection.” 


If no current selection exists, the Cut, Copy, and Clear commands should 
be disabled. If the Clipboard is empty, the Paste command should be dis- 
abled. If no Edit-menu command has been chosen, the Undo command 
should be disabled. The following figure shows disabled Edit-menu com- 


mands: 
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ae Si PtoDes 
ere Dir de ins 
Paste Shaft+Ins 
Clear Ded 


Select All 
Time/Date F5 


Word Wrap 


Figure 2.11 Edit Menu with Disabled Commands 


2.9 The Exit Command 


Each application should add an Exit command for quitting the program. 
The command should be placed at the bottom of the first menu of the 
application (unless an About... command is appended to the menu) and 
should be preceded by a line separator. The mnemonic recommended for 
access to this command is the letter “x.” If the user chooses the Exit com- 
mand after making changes without saving them, the application should 
display a dialog box warning of data loss. 


The optional Close command on the Control menu is not a substitute for 
an Exit command unless the application does not have a menu bar. 


2.10 The About... Command 


When the user chooses the About... command, the application should 
display a dialog box that contains the application name, the date the 
application was created, copyright information, and any additional infor- 
mation about the application, such as available workspace or the meaning 
of specific keys. The following figure shows an example of the About... dia- 
log box: 
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a 


See 


Menus 


Calendar 


Version 2.8 


Figure 2.12 About... Dialog Box 


If used, the About... command should be the last menu item on the Help 
drop-down menu or on the first drop-down menu of the application (fol- 
lowing the Exit command). It should be preceded by a line separator. Its 
recommended mnemonic is the letter “b.” 


When an application does not have any menus, the About... command 
may be appended to the Control menu following the Close command. The 
About... command is the only command that may be added to the Control 
menu. 


Every About... dialog box needs an OK button to allow the user to return 
to the application. Applications that provide additional help may include 
other buttons as well. 


For more information on dialog boxes, see Chapter 8, “Dialog Boxes.” 
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Accelerators 


3.1 Introduction 


Accelerators (shortcut keys) are keys that let the user choose a menu item 
more easily than the normal method of choosing the item. An accelerator 
is typically one of the following key combinations: ALT+key, CONTROL+key, 
SHIFT+key; it can also be a function key that the application has explicitly 
defined to represent a menu item, or a function key combined with the 
ALT, CONTROL, or SHIFT key. Pressing the a) carries out the item action 
just as if the user had displayed the menu and chosen the item. It is 
recommended that the menu name be highlighted when one of its associ- 
ated accelerators is pressed so that the user can identify the location of the 
corresponding command. 


3.2 Accelerator Rules 


Applications developed for Microsoft Windows can provide any number 
of accelerators but should restrict their use to the menu items used most 
often. An item should never have more than one accelerator. Applications 
should avoid using accelerator keys that are reserved for the system; like- 
wise, recommended accelerators should not be used for functions contrary 
to those described in this chapter and in Chapter 5, “Keyboard Interface.” 


3.3 Accelerator Names in Menus 


Applications that use accelerators should place the accelerator’s keyname 
beside the corresponding menu-item name in the menu. The keyname 
should appear to the right of the item name. 


If an accelerator is an ALT+key, CONTROL+key, or SHIFT+key combination, it 
should be shown on the menu as Alt+key, Ctrl+key, or Shift+key, where 
key is the keyname. There should be no space between Alt+, Ctrl+, or 
Shift+ and the keyname. If an accelerator is a function key, it should be 
shown as F'n, where F is uppercase and nis the digit. There should be no 
space between the letter and digit. | 


The following figure shows accelerator keynames listed to the right of the 
menu items: 
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Hatio 


' RirebkSe 


Cut Shiftebel 
Cony Stri+lns 
Paste Shift«las 
lear Sel 


Select All 
Tine/Date FS 


Figure 3.1 Accelerator Keynames 


3.4 Standard Control-Menu Accelerators 


Certain accelerators are assigned to Control-menu commands and may not 
be used by applications for any other purpose. The reserved accelerators 


are as follows: 
Key 


ALT-+F5 
ALT+F7 
ALT+F8 
ALT+F9 
ALT+F10 
ALT-+F4 


Action 


Invokes the Restore command. 
Invokes the Move command. 
Invokes the Size command. 
Invokes the Minimize command. 
Invokes the Maximize command. 


Invokes the Close command if this comer 
is present on the Control menu. 


3.5 Standard Edit-Menu Accelerators 


Applications that use accelerators with Edit-menu commands should use 


the following keys: 


Key 


ALT+BACKSPACE 
SHIF T+DELETE 
CONTROL+INSERT 
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Action 


Invokes the Undo command. 
Invokes the Cut command. 


Invokes the Copy command. 


Accelerators 


SHIFT+INSERT Invokes the Paste command. 
DELETE Invokes the Clear command. 


The SHIFT+DELETE, CONTROL+INSERT, and DELETE Edit-menu accelerators 
should not invoke their respective commands if there is no selection. The 
SHIFT+INSERT accelerator should not invoke the Paste command if the 
Clipboard is empty. The ALT+BACKSPACE accelerator should not invoke the 
Undo command if no Edit-menu command has been chosen. 


Note 
If an application provides an Edit menu, it must not use the standard 
Edit-menu accelerators for any other purpose. 


3.6 The Help Key 


In addition to these standard accelerators, the F1 key is recommended for 
use as the Help key. The user presses F1 to obtain more information about 
a subject. See Chapter 12, “Help Facility,” for more information about 
on-line help. 
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Selection 


4.1 Introduction 


Applications developed for Microsoft Windows that let the user copy infor- 
mation to the Clipboard or that have commands that act on the contents 
of the screen should provide a way to let the user select the information to 
be copied or acted on. The selection is one or more items that the user has 
chosen. These items will be used as input to a subsequent command. 


There are two kinds of selections: text and non-text. Text selections are 
such things as a word or phrase in a manuscript the user is writing. Non- 
text selections can be elther an item, such as a cell on a spread sheet, or a 
region on the screen, such as part of a drawing the user is making. 


Applications that provide selection should let the user select with either 
the keyboard or the mouse. Applications should use the keys and the 
mouse buttons recommended in Chapter 5, “Keyboard Interface,” and 
Chapter 6, “Mouse Interface.” 


4.2 Selection Highlighting 


Applications should mark the selection by highlighting it. Highlighting can 
be achieved by displaying the selection in reverse video (used for text and 
item selections) or by enclosing it in a rectangle (used for some graphic 
selections). 


When the window containing the selection is no longer active, the applica- 
tion should remove the highlighting. When the window becomes active 
again, the application should restore the highlighting. 


If the window containing the selection is no longer active but the applica- 
tion is still using the selection in some way, the application should keep 
the selection highlighted. For example, in Microsoft Windows Write, if the 
user selects a section of text, then chooses the Fonts command from the 
Character menu, a dialog box appears. The dialog box becomes the active 
window, but the text remains selected, as shown in the following screen: 
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rite — PRACTICE-DO0 
Edit Search (Character Paragraph Document 


Murphy & Allen, Realtors 
11958 165h Aue: Eas Seattle, WA 86987412 


goers 


PREPARING & HOME 


You can understany 7 


the buyer want to 
some tested tips 


Make minor repairs. Dripping faucets call attention to faulty plumbing. 
You should make sure all plumbing is in good working condition. If you 


Highlighted text 


Figure 4.1 Selected Text in an Inactive Window 


4.3 Text Selection 


When an application permits the user to select text, the following types of 
selection are recommended: 


Selection 


Insertion point 


Character 


Word 


Line 


Extended 
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Result 


User should be able to select a point between charac- 
ters to insert new characters. 


User should be able to select individual characters, 
including punctuation or a space. 


User should be able to select individual words. A word 
is any contiguous string of characters not containing a 
word-break character. Word-break characters are such 
things as new-line characters and tabs. 


User should be able to select whole lines. A line is any 
contiguous string of characters not containing a new- 
line character. 


User should be able to extend the existing selection to 
include additional characters. For example, the user 
should be able to extend a character or word selection 
to include several more characters. 


Selection 


All text selections, except the insertion-point selection, should be high- 
lighted. The insertion-point selection should be marked with a flashing 
caret (shown as a flashing bar or bitmap). 


An extended selection should always begin at the original selection and 
continue either to the left or to the right (or up or down). An application 
should not allow a selection to be extended in both directions at the same 
time. Instead, there should be one active edge of selection. If, when using 
the keyboard, the user extends the selection to the beginning or end of a 
line, the extension should move to the opposite end of the next line up (if 
moving left) or down (if moving ey Extending the selection up is the 
same as extending it to the left quickly; extending it down is the same as 
extending it to the right quickly. If, while extending the selection to the 
left (or right), the user moves the selection in the opposite direction, the 
application should remove the extended selection in the reverse order in 
which it was made. 


The application should let the user remove a text selection by making 
another selection, pressing a key, or clicking with the mouse. 


4.4 Editing Text Selections 


Applications that permit editing of selected text should follow these rules: 


e When text is inserted at an insertion point, the insertion point 
moves to the right and new characters are placed to the left of the 
insertion point (it does not put the character on the Clipboard). 


e When a character, word, or line is selected, inserting text removes 
the selected text and replaces the selection with an insertion point. 
The insertion continues as described in the previous rule. 


e When acharacter, word, or line is selected, deleting text removes 
the selected text. 


e Using the BACKSPACE key at an insertion point deletes the charac- 
ter to the left and moves the insertion point to the left. 


e Using the DELETE key at an insertion point deletes the character to 


the right of the insertion point (it does not put the character on 
the Clipboard). 
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4.5 Non-text Selection 


Applications that permit the user to select items other than text should 
provide the following types of selection: 


Selection Result 

Item User should be able to select individual items on the 
screen, such as filenames from a directory listing, or 
icons. 

Region User should be able to select the contents of a rec- 


tangular region on the screen. 


Applications should let the user make any number of item selections. The 
selections should be highlighted, appearing in reverse video. The user can 
extend the selection by selecting additional items, as shown in the follow- 
ing figure: 


Te ree aaa teva tL deviate a te ead ee ie Se Rhee li ae cae BEM Raat wah 


Figure 4.2 Selected Items in Reverse Video 


Applications should let the user select any rectangular region on the 
screen. The user begins the selection at any point and moves it any direc- 
tion to an end point. The start and end points mark the diagonally oppo- 
site corners of the rectangular region. While the user selects the region, 
the application should highlight the region to mark the user’s progress. 
The highlight can be a reverse-video display or an enclosing rectangle. A 
selected region is shown highlighted by an enclosing rectangle in the fol- 
lowing screen: 
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Selection 


The selected region has been moved. 


tac car Lan RR ERAN, tao ly Mae dee cre ene Peet a tele Ny eed 


a ha ah ae nT 
tyle Palette Options 


Figure 4.3 Selected Region Enclosed in Rectangle 


4.6 Discontinuous Selection 


A discontinuous selection is any non-text selection in which two or more 
non-adjacent items on the screen are highlighted. An application can per- 
mit discontinuous selections whenever the user needs to select multiple 
en from a list of items, such as two or more filenames from a directory 
isting. 


Applications should not permit discontinuous text selections. Instead, each 
new selection should clear the previous selection. 
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5.1 Introduction 


Since Microsoft Windows does not require a mouse or similar pointing 
device, applications should ensure that every menu item can be selected 
with the keyboard. (To test this, it is recommended that you unplug the 
mouse card and try every menu item with the keyboard.) 


To assist application design, Windows provides a built-in keyboard inter- 
face for accessing an application’s menus; for selecting the active applica- 
tion, window, or control; and for moving, sizing, enlarging, shrinking, and 
closing a window. For other actions, such as scrolling a window and select- 
ing objects in a window, the use of specific keys is recommended, but the 
application should carry out the actual operations. 


5.2 General Recommendations 


An application has a wide range of key combinations available in Win- 
dows. In selecting keys, use the following guidelines: 


e Use single keys for frequently performed, small-scale tasks. For 
example, in an application that is using split windows, a single 
function key, Fé, can be used to move the input focus clockwise 
from one subdivision of a window to another. 


e Use SHIFT+key combinations for actions that are complimentary to 
the actions of the key used alone. For example, if the Fe key moves 
the input focus clockwise from one subdivision of a window to 
another, the combination of SHIFT+F6 would be used to move the 
input focus counterclockwise. 


e Use CONTROL+key combinations for less frequent actions, or larger- 
scale tasks. For example, CONTROL+F6 could be used to move the 
input focus from one document window to another within the main 
window. 


e Avoid using ALT+key combinations since they are generally used for 
system tasks. 
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5.3 Reserved System Keys 


The reserved system keys are the built-in system keys Windows uses to 
access an application’s menus and dialog boxes. Applications can use some 
of these keys for normal input and output when the application has the 
input focus. Applications must never attempt to trap these keys. 


5.3.1 Keys Not to Be Redefined 


The following reserved keys are active at all times and must not be 


redefined by any application: 


Key 


ALT+F4 
ALT, SPACEBAR 


SHIFT+ESCAPE 
ALT, MINUS 


ALT-+TAB 


ALT+SHIF'T+TAB 


ALT+ESCAPE 
ALT+SHIFT+ESCAPE 


CONTROL+ESCAPE 
ALT+F5 

ALT+F7 

ALT+F8 

ALT+F9 

ALT+F10 

F10 or ALT 
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Action 


Closes the window. 


Selects the Control menu of the active 
window. 


Selects the Control menu of the active 
window. 


Selects the Control menu of the active docu- 
ment window. 


Selects the next active window, moving from 
front to back. If an icon is selected, it is 
restored to a window. 


Selects the next active window, moving from 
back to front. 


Selects the previously active window in the 
next active application, moving from front 
to back. 


Selects the previously active window in the 
next active application, moving from back 
to front. 


Reserved for future use. 

Restores the window to its previous size. 
Moves the window. 

Sizes the window. 

Shrinks the window to an icon. 

Enlarges the window to its maximum size. 


Sets the menu mode. 


Keyboard Interface 


5.3.2 Keys Reserved During Menu Use 


The following reserved keys are active when a menu has been selected. At 
other times, they may be redefined by an application: 


Key 


LEFT 


RIGHT 


DOWN 


ENTER 
ESCAPE 


Action 


Moves to the next column within a menu, or 
selects the next menu, moving from right to 
left. 


Moves to the next column within a menu, or 
selects the next menu, moving from left to 
right. 


Selects the command above the selected 
command in the selected menu. 


Selects the command below the selected 
command in the selected menu, or if no 
menu is displayed, displays the selected 
menu. 


Carries out the selected command. 


Cancels the selected menu. 


5.3.3 Keys Reserved During Dialog-Box Use 


The following reserved keys are active when a dialog box is displayed. At 
other times, they may be redefined by an application: 


Key 


TAB 
SHIFT+TAB 


SPACEBAR 
ENTER 


ESCAPE 


Action 
Selects the next active control, moving from 
left to right and top to bottom. 


Selects the next active control, moving from 
right to left and bottom to top. — 


Activates the selected button. 


Carries out the default action as defined by 
the default push button. 


Cancels the dialog box. 
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5.4 Recommended Keyboard Use 


Although applications can use all keys on the keyboard for their normal 
input operations, for the sake of a consistent keyboard interface, it is 
recommended that applications use the following keys for the actions 
listed. 


~ 


5.4.1 General Use Keys 


There are a number of common functions in applications. The following 
key assignments are recommended for these cases: 


Key Recommended Action 
Fl Reserved as the Help key. 
F6 Selects the next active subdivision of a 


window (a child window within a document 
window), moving clockwise. 


SHIFT+F6 Selects the next active subdivision of a win- 
| dow, moving counterclockwise. 


CONTROL-+F6 Selects the next active document window 
(a child window within the main window), 
moving from front to back. 


SHIFT+CONTROL+F6 Selects the next active document window, 
moving from back to front. 


ALT+F6 Selects the application’s next active non- 
child window (such as a modeless dialog 
box), moving from front to back. For infor- 
mation on modeless dialog boxes, see 
Chapter 8, “Dialog Boxes.” 


SHIFT+ALT+F6 Selects the application’s next active non- 
child window, moving from back to front. 

ALT+F1 Same as the Fl key. 

ALT+F2 Same as the F12 key. 


5.4.2 Keys Used for Moving and Selecting 


The following keys are recommended for selecting items, for formatting 
and selecting text or graphics, and for moving within a window. A key’s 
actions may vary according to whether it affects items, text, or graphics; 


therefore, some of the keys listed below have several recommended actions: 
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TAB 


SHIF'T+TAB 


ENTER 


LEFT 


RIGHT 


UP 


DOWN 


CONTROL+ LEFT 


CONTROL+RIGHT 


CONTROL+UP 


CONTROL+DOWN 


SHIFT+CONTROL+LEFT 


SHIF T+CONTROL+RIGHT 


SHIFT+CONTROL+UP 


SHIFT+CONTROL+DOWN 


Keyboard Interface 


Recommended Action 


Moves to the next item, moving from 
left to right and top to bottom; 
moves text right one tab stop. 


Moves to the next item, moving from 
right to left and bottom to top; 
moves text left one tab stop. 


Confirms or executes the default 
item; starts a new line of text. 


Moves to the item to the left of the 
current item; moves left one char- 
acter. 


Moves to the item to the right of the 
current item; moves right one char- 
acter. 


Moves to the item above the current 
item; moves up one line. 


Moves to the item below the current 
item; moves down one line. 


Moves to the left or beginning of a 
field, group, or section. 


Moves to the right or end of a field, 
group, or section. 


Moves to the top or beginning of a 
field, group, or section. 


Moves to the bottom or end of a 
field, group, or section. 


Moves the input focus and extends 
the selection to the left or beginning 
of a field, group, or section. 


Moves the input focus and extends 
the selection to the right or end of a 
field, group, or section. 


Moves the input focus and extends 
the selection to the top or beginning 
of a field, group, or section. 


Moves the input focus and extends 
the selection to the bottom or end of 
a field, group, or section. 
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PAGE UP 

PAGE DOWN 
CONTROL+PAGE UP 
CONTROL+PAGE DOWN 
SHIFT+PAGE UP 


SHIFT+PAGE DOWN 


SHIF T+LEFT 


SHIFT+RIGHT 


SHIF'T+UP 


SHIFT+DOWN 


INSERT 
SHIFT+INSERT 


CONTROL+INSERT 


DELETE 
CONTROL+DELETE 


SHIFT+DELETE 


BACKSPACE 


ALT+BACKSPACE 
HOME, 
CONTROL+HOME 
SHIFT+HOME 


SHIFT+CONTROL+HOME 
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Scrolls up one screen. 
Scrolls down one screen. 
Scrolls left one screen. 
Scrolls right one screen. ~ 


Scrolls and extends the selection up 
one screen. 


Scrolls and extends the selection 
down one screen. 


Moves the input focus and extends 
the selection left one unit. 


Moves the input focus and extends 
the selection right one unit. 


Moves the input focus and extends 
the selection up one unit. 


Moves the input focus and extends 
the selection down one unit. 


Toggles in the insert/replace mode. 


Inserts (pastes) the contents of the 


Clipboard. 


Copies the selection to the Clip- 
board. 


Deletes (clears) the selection. 


Deletes from the current position to 
the end of the line. 


Removes (cuts) the selection and 
puts it on the Clipboard. If there is 
no selection, it removes the character 
to the right and puts it on the Clip- 
board. 


Deletes the character or space left of 
the insertion point. 


Cancels the last editing action. 
Moves to the beginning of the line. | 
Moves to the beginning of the data. cme 


Moves and extends the selection to 
the beginning of the line. 


Moves and extends the selection to 
the beginning of the data. 


END 
CONTROL+END 
SHIFT-+-END 


SHIFT+CONTROL+END 


CONTROL+DIRECTION 


CONTROL-+SHIFT+DIRECTION 


CONTROL+SPACEBAR 


SHIFT+SPACEBAR 


Keyboard Interface 


Moves to the end of the line. 
Moves to the end of the data. 


Moves and extends the selection to 
the end of the line. 


Moves and extends the selection to 
the end of the data. 


Leaves the selection intact and 
moves in the indicated direction. 


Adds to a discontinuous selection, 
moving in the indicated direction. 


Adds to the current selection (per- 
mits discontinuous selection). 


Extends the selection from its previ- 
ous end point to the current location. 


5.5 Keys Used in Child Windows 


In applications that use a multiple-document interface, document windows 
should use the following key combinations to access Control-menu items: 


Key 


ALT, MINUS 
CONTROL+F5 


CONTROL+F7 
CONTROL+F8 
CONTROL+F9 
CONTROL+F 10 
CONTROL-+F4 


Action 
Selects the Control menu of the active docu- 
ment window. 


Restores the document window to its previ- 
OUS SIZeé. 


Moves the document window. 
Sizes the document window. 
Shrinks the document window. 
Enlarges the document window. 


Closes the document window. 


49 


Microsoft Windows Application Style Guide 


5.6 Keyboard Input Focus 


An application should acquire the keyboard input focus (current owner- 
ship of the keyboard) whenever it is the active window. Since only one 
window can have the keyboard input focus at a time, having the focus 
guarantees that the application receives all the input intended for it. 


An application should relinquish the keyboard input focus whenever the 
user moves to another window. This permits the new window to acquire 


the focus if necessary. The application should reacquire the focus when the 


user returns to the application’s window. 
Although Windows provides a mechanism to trap keyboard input (and cir- 


cumvent the input focus), applications should use this mechanism only 
when absolutely necessary. 
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6.1 Introduction 


Although the use of the mouse (or similar pointing device) is optional with 

Microsoft Windows, applications should use it liberally as an alternate 

method of input. In particular, applications should always use the mouse 
wherever it clearly improves the application’s performance. 


Note 


Since the mouse is the most common pointing device, for convenience, 
the word “mouse” is used in all discussions of pointing devices. How- 
ever, information about using the mouse pertains to other pointing 
devices as well. 


The following list defines the terms used to describe mouse movement: 


Mouse Movement Definition 

Point Move the mouse until the tip of the pointer rests 
on the desired item or area. 

Click Quickly press and release the mouse button. 

Drag Press the mouse button and hold it down while 


moving the mouse. 


Double-click Click the mouse button twice in rapid succession. 


6.2 Recommended Mouse Use 


As it does with the keyboard, Windows provides a built-in mouse interface 
for accessing an application’s menus; for selecting the active application, 
window, or control; and for moving, sizing, shrinking, enlarging, and clos- 
ing a window. Other specific actions should correspond to the mouse but- 
tons and movements listed below. The application is responsible for carry- 
ing out the actual operations. 


The left mouse button should be used for all of the application’s actions. 
Other buttons may be used for shortcuts but should not be required by the 
application. Applications should use the mouse as shown in the following 
lists. 
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6.2.1 Text Selection with the Mouse 


The following list describes the mouse movements recommended to select 
text: 


Mouse Movement Action 

Click Moves the insertion point to the area being 
pointed to. 

Double-click Selects a word. 

Drag Selects text from the area where the mouse but- 


ton is pressed through to the release point. 


SHIFT-+-click Extends the selection from the insertion point to 
the area being pointed to. 


SHIFT+drag Extends the selection from the area pointed to 
when the mouse button is pressed through to the 
release point. 


6.2.2 Item Selection with the Mouse 


The following list describes the mouse movements recommended to select 
items: 


Mouse Movement Action 

Click Selects the item being pointed to. 

Double-click Confirms or executes the item being pointed to. 
Drag Extends the selection from the area pointed to 


when the mouse button is pressed through to the 
release point. 


SHIFT+click Extends the selection from the input focus to the 
area being pointed to. 


CONTROL-+click Selects discontinuous items, adding an area or 
unit to the selection. 


CONTROL+drag Selects discontinuous items, keeping the current 
selection and creating an additional selection 
from the area where the mouse button is pressed 
through to the release point. 
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6.3 Mouse Pointers 


Applications should use mouse pointers that are appropriate for the 
current action. When the user needs to select items by clicking with the 
mouse, the application should provide a pointer. A variety of pointers may 
be _ for the same action when the pointer is in different parts of the 
window. 


Three mouse pointers are shown as follows: 


Pointer Description 


\ Arrow pointer. Selects menus, items, commands, etc. 

if I-beam pointer. Indicates an insertion point. 
Hourglass pointer. Indicates that an operation is tak- 

nA ing place even though no output is being sent to the 
screen. - 


6.4 Mouse Capture 


Under normal operating conditions, an application receives mouse input 
only when the mouse pointer is in the application’s window. Applications 
that want to receive mouse input from points outside the window can cap- 
ture the mouse input, but should do so sparingly. When mouse input is 
captured, the user cannot select menus or change to another application. 
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7.1 Introduction 


Applications developed for Microsoft Windows that use filenames to create 
and open files should use a consistent approach when forming filenames 
from user input. 


7.2 Default Filename Extension 


Applications should use the same extension for all data files whenever pos- 
sible. In particular, an application should have a default filename exten- 
sion that it appends to a data filename whenever the user does not supply 
one. The default extension should be unique so that the user can distin- 
guish one application’s data files from another or use the file to invoke the 
application implicitly. The extension can be one, two, or three characters. 


7.3 Filename Conventions 


Applications should apply the following rules when forming complete 
filenames from user input: 


e Ifthe user supplies a filename without a pathname, by default, the 
application should search the current directory. If the file is not 
found, the PATH variable should be searched. 


If the user is saving a file and the file is not found in the search just 
described, it should be saved in the current directory. In some 
cases, a Save As... dialog box will be generated. If the file is in the 
current directory, the application should show only the filename. If 
- file is in another directory, the complete pathname should be 
shown. 


e Ifthe user supplies a pathname, the application should decide if it 
is appropriate. If it is not, the application should display an error 
message and prompt for a new name. 


e If the user supplies a name without an extension, the application 


should append the application’s default extension. The user should 
also log the default extension in the win.znz file. 
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the extension (for example, abc.new), the application must not 
append the default extension. The application may log the user- 
supplied extension in the win.inz file, though this isn’t required. If 
the user changes the extension in win.zni, however, the application 
should accept the new extension as its default. oo 


e Ifthe user on or a null extension (for example, abc.), or changes 


e Ifthe filename is too long, the application should generate an 
appropriate error message. 


7.4 Temporary Filenames 


Applications that create temporary files (files to be used during execution 
only) should use names as shown in the following example: 


Tilde 


ieee nunber 


“HSP2 659 . TMP 


Temporary extension ee ane 
Application filename extension 


The ~ is a required tilde. 


The filename extension is the 1-, 2-, or 3-character default extension used 
by the application. 


The hezadecimal number is unique to each new temporary file. This num- 
ber is created by the Windows Get TempFileName function. 


The temporary extension .émp is required. 


Since it is possible to run multiple copies of an application simultaneously, 
each temporary file must have a unique name to prevent one file from 
overwriting another. The GetTempFileName function can be used to 
assign a unique name to each file. 


Temporary files should always be placed in the directory specified by the 


user’s DOS TEMP environment variable, if one is specified. If no directory 
is specified, the files should be placed in the root directory. 
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7.5 Prompting for Directories and Filenames 


Commands that require a filename or directory name to carry out their 
actions should prompt for the names using a dialog box with the following 
format: 


Edit control 


Current directory 
Open File Name: ; 


PRACTICE .0OC A i 


Files in C:\SAMPLES 


Proposed filename 


List box 
Figure 7.1 Dialog Box Requesting a Filename 


The edit control is used to enter the desired filename or directory name. 
The list box lists the contents of a directory. 


The application should place the current filename in the edit control as the 
proposed filename. If there is no current file, the application should pro- 
pose an appropriate default name. The application should also select the 
proposed name for editing. This lets the user delete the name with a single | 
keystroke 1f another name is desired. 


The application should list the partial contents of the current directory in 
the list box. In particular, it should list all filenames that end with the 
application’s extension and all directory names. Whenever the user selects 
a filename from the list box, the application should copy this name to the 
edit control. 


In most applications, the available disk drives and subdirectories will be 
displayed in the list box along with the current directory listing. However, 
some applications may use separate list boxes for this purpose, as shown in 
the following example: 
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Separate list box showing 
disk drives 


Files in C:\SAMPLES 


Figure 7.2 Dialog Box with Separate Disk-Drive List Box 


For more information on using list boxes, see Microsoft Windows Program- 
ming Tools. 
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8.1 Introduction 


Applications developed for Microsoft Windows should use dialog boxes to 
request input from the user and to display information that is not part of 
the application’s normal output. A special type of dialog box, called the 
message box, is used to display error messages and warnings. Message 
boxes are described in Chapter 9, “Message Boxes.” 


8.2 Dialog-Box Types 


Dialog boxes can be modal or modeless. A modal dialog box prevents the 
user from continuing to work with the application until some action is 
taken. A modeless dialog box lets the user continue working with the 
application. | 


Applications should use modal dialog boxes for requesting command input. 
In this way, a modal dialog box ensures that the user responds to the 
input request before continuing to work. 


Applications should use modeless dialog boxes for displaying information 
that does not require immediate attention. Modeless dialog boxes typically 
display information that the user can use while working with the applica- 
tion (such as a Help dialog box). Unlike modal dialog boxes, modeless dia- 
log boxes can be moved out of the way by the user so that they don’t 
obscure the user’s work. 


There are three types of dialog boxes: 
Dialog Box Description 


Modeless This dialog box is a separately functioning win- 
dow. The user can continue to work with the 
application that called the dialog box or with any 
other application. The user can move the mode- 
less dialog box if it obscures the work area and 
can close it at any time by using the dialog box’s 
Control menu. 


Application modal This dialog box requires attention before the user 
can continue to work with the application that 
displayed it. This dialog box does not prevent the 
user from working with other applications. 
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System modal This dialog box requires attention before the user 


8.3 


can continue to work with any application. Use 
this dialog box only when absolutely needed, such 
as when warning about an impending fatal sys- 
tem error or an unrecoverable error that could 
disrupt system operation. 


Dialog-Box Appearance 


The appearance of an application’s dialog boxes should be defined by the 
following rules: 


8.4 


Dialog boxes should not contain menu bars. 


Dialog boxes should disable and gray (or remove) all unused 
Control-menu commands. 


A modal dialog box should have a framed border. 
A modeless dialog box should have a title bar and a Control menu. 


A modeless dialog box should have a caption in its title bar. The 
caption should be the name of the command that created the box. 


A modeless dialog box should disable and gray (or remove) all 
Control-menu commands except Move and Close. 


Controls 


Dialog boxes generally contain controls with which the user can supply 
information for the corresponding menu item. The controls can be any 
combination of the following: 


Control Description 

Push button = Acommand button, labeled to indicate what it does 
(for example, OK, Cancel) 

Radio button An option button located in a group of option buttons 
from which the user may select one option 

Check box An option that is on or off 

List box A box listing available choices 

Edit control A box for entering information 
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The following dialog box shows several types of controls: 


Radio buttons 


errr rTTs 


[_j New Line [) Local Echo 
} Text size @ Large 


Check boxes 


Lines in Buffer: 


Edit control 


Translation: i 
Deninark/ Norway 
enner List box 


Push buttons 


Figure 8.1 Controls in a Dialog Box 


The number and type of controls depend on the dialog-box type and the 
input needs of the corresponding menu item. 


The application should always provide proposed values for the information 
requested in the dialog box and give the user the option of selecting the 
proposed values or entering new values. Proposed values can be based on 
previous information or on standard defaults. 


8.4.1 Control Labels 


Controls should have appropriate labels, as defined by the following rules: 


Control labels should begin with a capital letter. 


All edit controls should have a static-control label that ends with a 
colon. 


Labels on radio-button groups should not contain a colon. 


Each control label should have a unique mnemonic, or the group 
label can be given the mnemonic. Visual indication and rules for 
selection are the same as for mnemonics in menus. For more infor- 
mation on mnemonics in dialog boxes, see Section 8.4.2. 


Inactive controls should be indicated by a grayed label. Inactive 
controls can still be selected by the user. It is up to the application 
to decide its response. 
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The following dialog box shows the recommended format for control 
labels: 


Phone Settings 
Connect to: [id 


Dial Type @Tone © Pulse 
Speed ©Slow @ Fast 


Wait for Tone (2-15): 2 
Wait for Answer eae 


Figure 8.2 Control Labels 


8.4.2 Mnemonics in Dialog Boxes 


When mnemonics are used in dialog boxes, they are defined by the applica- 
tion in the same way that they are when used in menus. 


If the control has a label, the mnemonic may be one of the letters in the 
label. If the control has a static-control label, as is the case with an edit 
control or list box, one of the letters of the static-control label should be 
used as the mnemonic. 


If the mnemonic letter associated with the control is unique within the dia- 
log box, the control is automatically selected when the user presses the 
corresponding key. If not, the input focus moves to the control, but the 
user must press the SPACEBAR to select it. If the mnemonic letter is associ- 
ated with a static-control label such as a text field, the input focus auto- 
matically moves to the next control in the enumeration sequence, which 
may be a list box or edit control. If there is no match between any control 
and ALT+mnemonic, pressing such a key combination results in a system 
beep. 


8.5 Default Push Buttons 


Every modal dialog box should have a default push button with which the 
user can provide the most reasonable response to the dialog box. The 
default button has a bold border. For most dialog boxes, the default but- 
ton carries out the command. In others, the button cancels the command. 
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In all cases, the ENTER key should activate the default push button, and 
the SPACEBAR should activate the selected button. The ESCAPE key should 
cancel the dialog box (if the dialog box has a Cancel button). 


When the user moves between push buttons, the bold outline associated 
with the default action will move as the input focus is moved, allowing the 
user to confirm the new selection with the ENTER key or the SPACEBAR. If 
the user moves by tabs beyond the last push button in the sequence, the 
bold outline and default action return to the original push button. 


8.6 Required Buttons 


Dialog boxes that request input should provide at least one push button to 
carry out the requested action and one to cancel it. In most dialog boxes, 
the OK and Cancel buttons are used for these purposes. The OK button 
(the default button) directs the menu item to continue its action with the 
information supplied. The Cancel button is used to cancel the menu item. 
In cases where the default or suggested choice is negative, Yes and No but- 
tons are generally used, with the No button as the default. This avoids the 
confusion that might occur from having the Cancel button be the default 
in this case. The recommended position for these push buttons is at the 
upper-right edge of the window with Cancel under OK. 


When a button cannot be chosen, the label in the button should be grayed. 


8.7 Dialog Boxes with Multiple Controls 


Dialog boxes that contain multiple controls should use the controls in the 
following ways: 
e When a push button is chosen, its related action is carried out. 


e When check boxes and radio buttons are selected, they change 
their state (from selected to not selected, or vice versa). — 


e The TAB key moves the input focus from one section of the dialog 
box to another. 


e The SPACEBAR activates the selected button. 
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8.8 Dialog Boxes Without Push Buttons 


It is recommended that all dialog boxes have push-button controls, though 
some may not. Applications that use dialog boxes without push-buttons 
should enable the ENTER and ESCAPE keys to let the user carry out default 
actions. The application should interpret the ENTER key as confirming or, 
where appropriate, as executing the actions in the dialog box. Once the 
action is confirmed, the dialog box should be closed. The application 
should interpret the ESCAPE key as canceling the dialog box without carry- 
ng an action. In modeless dialog boxes, the ESCAPE key closes the dia- 
og box. 


8.9 Sizing Dialog Boxes 


Dialog boxes must be sized to fit on all screens that the application will 
use for display. Calculate the maximum size of a dialog box by using the 
following formulas: 
e Width: 
(screen width) /(width of system font)]*#4=maximum dialog units 
e Height: 
(screen height)/(height of system font)|*8=maximum dialog units 
For device-independent applications, the recommended system font is 
80 X 24 characters. The corresponding dialog boxes would be a maximum 


of 320 X 96 dialog units. It is recommended that a dialog box take up no 
more than 75% of the screen. 


8.10 Moving Between Controls 


Moving the input focus within a dialog box is accomplished either by the 
use of general keys such as TAB and SHIFT+TAB (moving backwards by 
tabs), or by the use of mnemonics. 


The normal order of movement within a dialog box should be from left to 


right and from top to bottom. The following list describes the rules of 
moving and selecting within a dialog box: 
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Key Action 

TAB or SHIFT+TAB Moves the input focus from one con- 
trol to the next within the dialog 
box. 

ALT+mnemonic letter Moves the input focus directly to a 


control within a dialog box; if the 
control is a push button, it activates 
the button. 


Mnemonic letter Moves the input focus directly to a 
control within a dialog box, unless 
the input focus is in an edit control 
or list box. If the control is a push 
button, it activates the button. 


DIRECTION Moves the input focus and selects 
within a group of radio buttons. 
DIRECTION; TAB; or SHIFT+TAB Moves the input focus within a group 


of check boxes. 


8.11 Dialog-Box Appearance 


This section contains suggestions for design and text format that you may 
want to use in creating dialog boxes for your applications. Following these 
guidelines will help ensure a consistent user interface. 


8.11.1 Push-Button Design 

Push-button height should be 1-1/2 times as high as the tallest character 
in the button name and also should include space for the dotted box, 
which marks the input focus. 

The first letter in the push-button name should be a capital. All other 
characters in the name should be lowercase. 


8.11.2 Control Placement 


Controls in a dialog box should be located as follows: 


e Place horizontal scroll bars below the window to be scrolled. 


e Place vertical scroll bars to the right of the window to be scrolled. 
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e Label edit controls with static-control text. 


e Related radio buttons should be grouped in one of two ways. The | 
first method is to use the WS_GROUP window style to set the 
style for the first and last buttons in a group. This allows the user 
to move within the group using the DIRECTION keys. The second wae 
method is to enclose the related radio buttons in a group box. A a 
group box is a rectangle that groups controls together. 


Examples of both methods are shown in the following figure: 


@ ANSI © OEM 


Font Family 

© Roman © Modern 

@ Swiss © Decorative 
O Script © Unknown 


Figure 8.3 Related Radio Buttons 


ene 
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9.1 Introduction 


A message box is a special dialog box through which an application can 
display error messages and other important information. Message boxes 
are modal dialog boxes and require immediate attention by the user before 
work with the application can proceed. Applications developed for Micro- 
soft Windows should use message boxes only when an error occurs or when 
the application must supply information that the user needs in order to 
complete an action. 


9.2 Message-Box Types 


There are four types of message boxes; each type has an appropriate icon 
that should be located in the upper-left corner of the dialog box, as shown 
in the following list: 


Icon Message Box Description 


Status Informs the user that a task is in pro- 
gress. [t also can specify an action that 
the user must complete before a task can 
proceed. This message box contains no 
choices for the user to make. 


Warning or Warns or reminds the user of the action 

Note about to be taken. This message box 
asks for a user response and may contain 
choices for the user to make. 


Warning or Warns the user of the consequences of 

Caution carrying out an action, and requires the 
user to give instruction on how to pro- 
ceed. The box often contains Yes, No, 
and Cancel push buttons. This message 
box usually appears when data could be 
lost as a result of proceeding, for exam- 
ple, when the user deletes a file. 


qe k 


Stop Informs the user of a serious system- 
related deficiency that must be remedied 
before any action can be carried out. 


© 
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Only the Stop message box should be system-modal. All other message 
boxes should be application-modal. See Chapter 8, “Dialog Boxes,” for 
more information. 


Note 


Applications should use system-modal message boxes only when they 
encounter a condition that 1s the result of a system-related problem or 
when the condition may dramatically affect other applications running 
on the system. 


9.3 The System Beep 


Applications may use the system beep to signal a minor and obvious error, 
such as moving from the client area into a menu while pressing the mouse 
button. 


9.4 Message-Box Captions 


At a minimum, every message box should have a title bar and caption. 
The caption should include only the name of the application. For example, 
applications should not use “WARNING?” or exclamation points in a cap- 
tion. The text of the message box should clearly specify whether the mes- 
sage ls a warning or error message. If the message box indicates a system- 
related error, the caption “System Error” should be used. 


9.5 Push Buttons in Message Boxes 


Message boxes should contain only push buttons. Other control types are 
inappropriate in message boxes. Windows provides the following sets of 
push buttons for use with message boxes: 
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Push Button Description 
OK Used when no explicit action is required. 
OK or Cancel Used when OK is the default and the user has the 


option of canceling the command. 


Yes or No Used in an interrogatory message or warning 
when the default is No and the user has the 
option of proceeding with the command. 


Yes, No, or Cancel Used in an interrogatory message or warning 
when the user has the Yes and No options within 
the command, as well as the option to cancel the 
command and continue working with the applica- 
tion. Yes is the default. 


Retry or Cancel Used when a device error occurs, such as no disk 
in the disk drive. The user should cancel the com- 
mand or retry the operation that causes the error. 
Applications must not let the user ignore any 
device error. Retry is the default. 


The best or safest response should always be shown as the default button. 
If OK is used, it should be the default button. 


Buttons should never be ambiguous or redundant. For example, if an error 
message requires only acknowledgment, the OK button is sufficient; a Can- 
cel button is unnecessary. 


9.6 Keyboard Use 


Message boxes use the same keyboard support as other dialog boxes. The 
TAB key moves between buttons, the SPACEBAR activates the selected but- 
ton, the ENTER key activates the default button, and the ESCAPE key can- 
cels the message box (when the box contains a Cancel button). 


9.7 Flashing for Attention 


Any application that wants to display a message box when it or any of its 
child windows is not active should flash its title bar or icon, and beep to 
attract the attention of the user. The application should postpone display- 
ing the message box until the user makes the application active. 
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On system-critical or potentially unrecoverable errors, the application 
should display a message box. No flashing is recommended. 


9.8 Sample Message Boxes 


The following are some sample message boxes that can be shared by appli- 
cations that have standard File menus: 


e Ifthe user chooses the New or Open..: command in the File menu 
after changes have been made during the current session, a mes- 
sage box with the following format should be displayed: 


W/ Save current changes: ABC.TXT 


Figure 9.1 Dialog Box with Warning 


e Ifthe user chooses the Save As... command and then attempts to 
save the file under the name of an existing file, a message box with 
the following format should be displayed: 


Figure 9.2 Save As... Dialog Box with Warning 


e If the user invokes an application with the name of a data file that 
does not exist, a message box with the following format should be 
displayed: 
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W/ BEATLES .TXT not found ~ Create New File? 


Figure 9.3 Dialog Box with Warning 


If the user chooses the Yes button, the application should display 
the filename in the title bar and as the default field in a Save As... 
dialog box. If the user chooses the No button, the application 
should ignore the filename and continue operation as if no file had 
been specified. 


If the user chooses Yes, and the application displays the filename, 
it should also attach the standard extension unless the user sup- 
plies one. 


e [fan application has a Print command, it should display a print 
message box whenever it sends a file to the printer. The caption 
should contain the application’s name only. The dialog box should 
appear in the following format: 


TEST .1XT 


Sending 
text 


to printer 


Figure 9.4 Dialog Box with Print Message 


The name of the file appears in uppercase letters. The dialog box 
should also have a centered Cancel button. 


9.9 Message-Box Text 


Message-box text should describe the problem or error as clearly as possi- 
ble. ‘The message may suggest how to remedy the problem, but it should 
not be longer than two to three lines of text. Technical descriptions of the 
problem should not be used. 
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When writing text for a message box, do the following: 
e Use “Cannot” instead of “Can not” or “Can’t.” 


e Use “Not enough...to....” instead of “Disk is full, save not com- | 
pleted.” The following example is correct: i 


Not enough disk space to save PICTURE.MSP. 
e Do not put the name of the application in the message. 


e Do not imbed colons in the message. 
The following example is correct: 
Cannot read X.DAT. 

This example is incorrect: 


Cannot read: X.DAT. 
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10.1 Introduction 


Cooperation between applications is the key element in making Microsoft 
Windows a shared environment for applications. Applications should do 
the following: 

e Use the CPU sparingly. 


Applications that perform extended computations should yield con- 
trol whenever possible to let other applications complete their 
tasks. 

e Use the screen display only when active. 


Inactive applications should alert the user with a flashing title bar 
or icon if they need to display a dialog box. The user then can 
activate the application. 


e Use only as much memory as needed. 


e Use discardable code segments. 


Applications that consist of small, discardable code segments are 
much easier to move and swap when available memory is short. 


e Avoid fixed-memory objects. 


10.2 Loading and Initialization 


Applications should display their initial screen setup as soon as possible 
after loading. They should not leave a window empty for a long period 
of time. 


10.3 Yielding and Time-Critical Operations 


All applications should yield control whenever possible to allow other 
applications to access the CPU. For reasonably short operations where 
control is crucial, such as loading or saving a file, applications should 
complete the full operation as quickly as possible. 
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10.4 The System Hourglass 


All applications should display the system-hourglass pointer when they 
begin lengthy or dead-air (pause in activity) operations. This informs the 
user that interaction with the application is not currently possible. The 
hourglass should be displayed with both keyboard and mouse interfaces. 
The hourglass pointer is shown as follows: 


xl 


Figure 10.1 Hourglass Pointer 


10.5 Dead Air 


Unless waiting for user input, applications with the input focus must not 
present any pause in activity (dead air) that lasts longer than five seconds. 
Applications that require long delays in some operations should signal the 
user in some visible way that the operation is in progress, 


10.6 Memory Use 


Applications should cooperate in using memory. Applications should 
always determine whether there is sufficient space to operate in RAM as 
well as on the disk. If there is not, the application should display an 
appropriate message to let the user know that it is not possible to run in 
the current environment. 


Applications should be designed to use only as much memory as ls reason- 
ably required to run the application. 


84 


Cooperation 


10.7 File Use 


Applications should always close files located on a floppy disk when not 
explicitly carrying out disk operations. Leaving these files open can cause a 
system failure. It is an application’s responsibility to ensure that errors, 
such as the user’s removing a disk from the drive without closing a file, do 
not cause the system to fail. 


10.8 Color Use 


An application should use color wherever appropriate; however, considera- 
tion also must be given to how the program looks on monochrome 
displays. 


The system maintains default color settings that allow the user to adjust 

the color of various parts of the window. An application should use these 

default settings, unless it needs to regulate the color of a particular item. 

ne application may override the default settings, but it must not change 
them. 
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International Concerns 


11.1 Introduction 


Software companies are reaching out to international markets for 
increased sales. Competition from local products has increased dramati- 
cally. To reach these markets, applications developed for Microsoft Win- 
dows should be fully localized. You should design your product from the 
start with international markets in mind. 


This chapter summarizes the localization concerns you should consider 
when writing an application. Following these instructions will make your 
application easy to translate into various languages. 


11.2 Resource Files 


If the following are used in an application, they should be placed in the 
application’s resource file: menu items, menu bars, dialog boxes, pointers, 
icons, bitmaps, fonts, strings, and accelerators. This will allow a non- 
technical person to translate menus and messages and to resize and change 
the layout of dialog boxes. This person does not have to know anything 
about the source code of your application. Including this information in 
the resource file will dramatically cut the time required to bring your 
application to a new market. 


11.3 Character Sets and Keyboards 


Foreign countries use characters that are above 127 in the ANSI character 
set. These characters do not appear on US keyboards, and international 
keyboard layouts may differ from the layout of US keyboards. These 
ana can lead to difficulty when selling products in international 
markets. 


Since Windows uses the ANSI character set, you should consider adding a 
conversion program to your application. In international markets, you will 
always be using characters above 127 from the 8-bit character set. Below 
127, there is no difference between ASCII and ANSI. Above 127, you will 
encounter problems if you are loading a file created using the ASCII set 
into your Windows application. You should use the OemToAnsi and 
AnsiToOem functions to create a two-way conversion program. The 
conversion program also should recognize any file that it did not create. It 
should then invoke a dialog box to ask if the user wants to convert that 
file to the application’s Windows format. 
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11.4 Formats 


Different countries use different formats for numbers, currencies, time, 
dates, and measures, so porting an application to another country may be 
difficult. Windows provides you with a way to solve this problem. When 
requesting any of the above-mentioned values, your application should go 
to the win.ini file. Win.ini has an international section that contains all 
the values for the particular country Windows is installed for. At the time 
of installation, the setup program creates an international table in win.inz 
and puts all these values in it. The values entered are based on the user’s 
choice of a particular country’s keyboard. The following is a list of the 
values set in the jintl] section in win.ins: 


Setting Description 

i{Country= Country code, see your DOS manual for details. 
iDate= 0 for mdy (month, day, year), 1 for dmy, 2 for ymd. 
iCurrency= O for currency-symbol prefix, no separation. 


1 for currency-symbol suffix, no separation. 
2 for currency-symbol prefix, one-character separation. 
3 for currency-symbol suffix, one-character separation. 


iDigits= Number of significant decimal digits in currency. 
iTime= O for 12-hour clock, 1 for 24-hour clock. 
iLzero= O for no leading zeros, 1 for leading zeros. 
$1159= Trailing string from 0:00 to 11:59. 

s2359= Trailing string from 12:00 to 23:59. 

sCurrency= Currency-symbol string. 

sThousand= Thousands-separator string. 

sDecimal= Decimal-separator string. 

sDate= Date-separator string. 

sTime= Time-separator string. 

sList= List-separator string. 

dialog= Is always yes. This enables the Country Settings com- 


mand in Control Panel’s Preferences menu. 


These format settings must not be hardcoded. An application must get 
these values from the win.zni file. 
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The following are sample US settings from the [intl] section in win.ini: 


[intl] 


iCountry=1L 
iDate=0 
iCurrency=0 
iDigits=2 
iTime=0O 
iLzero=0 
s1159=AM 
s2359=PM 
sCurrency=$ 
sThousand=, 
sDecimal=. 
sDate=- 
slTime=; 
sList=, 
dialog=yes 


11.5 Additional Software Design Tips 


To facilitate their use internationally, applications developed for Windows 
should do the following: 


An application should include the following in its resource file: 


Any text string that the user may see in the form of a screen 
message 


All dialog-box text and coordinates 
All child-window text and coordinates 


An application’s dialog boxes and child windows should not take 
up more than 75% of the screen space. This restriction allows the 
enlargement of the dialog box and/or child window when translat- 
ing the message strings. 


An application should never rely on the position of a string in a 
menu, dialog box, or child window. This saves you from having to 
modify the source code if the position of the string changes when it 
is translated. 


An application should never rely on the length of a string in a 


menu, dialog box, or child window. When translated, the length of 
the string may change. 


91 


Microsoft Windows Application Style Guide 


92 


If a string contains variables, these variables should be able to 

be relocated anywhere within the body of the string. In different 
languages, the position of a word in a string may vary. The recom- 
mended way of representing variables is the use of “%%” as a 
placeholder. The “%%” placeholder then can be relocated by the 
translator anywhere within the string. The following system mes- 
sage 1s an example of this: 


COPYING FOO.DOC 
The variable is foo.doc. In French, this becomes: 
COPIE DE FOO.DOC EN COURS 


The variable foo.doc had to be relocated in the middle of this 
string. In the msdos.rc file, the string appears as: , 


"COPYING %%" 


Accelerator keys should not be hardcoded. They should be able to 
be modified in the application’s resource file. 


ALT+key combinations should be examined carefully. Some interna- 
tional keyboards use certain ALT+key combinations to enter certain 
characters. 


Application names, as well as filenames and extensions produced by 
the application, should not be hardcoded. They should be able to 
be modified in the application’s resource file. | 


An application should not use any OEM-specific virtual keys, with 
the exception of alphanumeric keys. Using these OHM-specific vir- 
tual keys prevents you from porting the application to interna- 
tional markets that use different keyboard layouts, unless you 
make substantial code modifications. 


An application should accept and output the full range of the 8-bit 
ANSI character set. Your application should not be dependent on 
the US character set or any specific country’s character set. 


An application should support both metric and English measure- 
ment systems. 


If an application is doing any kind of sorting, it should account for 
the various international sorting schemes. 
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12.1 Introduction 


To allow users to request on-line information about your Microsoft Win- 
dows application, you may decide to include a help facility in the applica- 
tion. Two main types of help may be offered: general information and 
context-sensitive information. If on-line help is available, the user must be 
able to access it both from the keyboard and by using the mouse (or simi- 
lar pointing device). 


12.2 Access to Help 


The help facility can be provided as either a push-button control in the 
menu bar, which responds with a dialog box, or a menu name, which 
causes a menu to appear. 


If the help facility is included as a push-button control, a separator is 
drawn in the menu bar; the push button can be chosen with the mouse or 
the keyboard. However, the user cannot choose the push button by using 
the standard menu-selection keys. The application should implement the 
F1 key as the access key. 


If the apphcation includes the help facility as a menu name and provides a 
menu with it, no separator is drawn in the menu bar. In this case, the help 
facility can be accessed through the standard menu interface. The applica- 
tion should place the Help-menu name at the far-right side of the menu 
bar, and the F1 key should be implemented as the accelerator key for 
selecting the menu. 


In the following example, the help facility is provided as a push-button 
control in the menu bar: 


Figure 12.1 Help Facility as Push-Button Control 


It is also possible to provide help within an application’s dialog boxes. To 
include this type of help facility, a Help button should be added to the dia- 
log boxes and the F1 key should be supported as the access key. 


95 


Microsoft Windows Application Style Guide 


12.3. General Help 


An application can provide help by allowing the user to obtain general 
help information. When the user chooses the help facility, the application 
should display a dialog box with the following form: 


Help Topics 


Using Help 
Formatting a document 


Setting margins 
Changing fonts 
Changing margins 


Figure 12.2 Help Topics Dialog Box 


The dialog box contains a list box showing all of the topics the user can 
get information about. The user should be able to choose a topic by any of 
the following methods: 


e Choose the Help button or press the ENTER key to choose the 
currently highlighted topic. 


e Select a topic, then choose the Help button or press the ENTER key. 


e Double-click a topic with the mouse. 


The Help button should be the default button. If the list box contains 
more topics than can be shown at one time, the list box should have a 
scroll bar to allow the user to request additional topics. Choosing the Can- 
cel button should remove the Help Topics dialog box and let the user con- 
tinue working with the application. 


When the user chooses a topic, the application should display a dialog box 


that contains help information about the selected topic. The dialog box 
should have the following form: 
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Changing Margins ; 
You can change margins by selecting the 
Document menu and choosing the Page Layout ae 


command, which causes a dialog box to 
appear. In the Margins text boxes, type 


Figure 12.3 Help Information Dialog Box 


If the user chooses the Topics button, the application should display the 
Help Topics dialog box. If the user chooses the Next button, the applica- 
tion should display the Help Information dialog box for the next topic on 
the list. The Next button is the default button. If the user chooses the Pre- 
vious button, the application should display the Help Information dialog 
box for the previous topic. Choosing the Cancel button or pressing the 
ESCAPE key should return the user to the previous location in the applica- 
tion. 


If more information is available than can be displayed in the list box, 
scroll bars should be provided to allow the user to view the rest of the 
text. 


12.4 Context-Sensitive Help 


An application can also provide help by implementing the F1 key as the 
key that places the application in “help mode.” In this mode, the next 
item the user selects (menu, scroll bar, control, etc.) should display a Help 
Information dialog box that gives information about the selected item. 
This 1s known as context-sensitive help. The dialog box has the same for- 
mat as the one shown in Figure 12.3 in the preceding section. 


When the user presses the F1 key, the mouse pointer changes to a question 
mark. If no mouse is installed, a question-mark pointer is displayed in the 
middle of the application window. If the application is displaying a dialog 
box when the Fi key is pressed, a Help Information dialog box that lists 
information about the application’s dialog box should be displayed. 


When the user presses the ESCAPE key, the application should cancel the 
help mode and display the user’s previous location in the application. 
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Multiple-Document Interface 


13.1 Introduction 


Some applications developed for Microsoft Windows may support the 
viewing of multiple windows from within an application’s main window. 
The windows may provide different views of the same data or may con- 
tain different documents or sets of data. Such applications should use a 
multiple-document interface that allows the user to manage associated 
windows easily from the main window. 


An application with multiple windows should use child windows. The child 
windows should be clipped so that they can reside inside the application’s 
main window. The following figure shows an application using multiple 
windows: 


Figure 13.1 Multiple-Document Child Windows in a Main Window 


13.2 The Main Window 


The main window’s Control menu affects the main window (window posi- 
tion and size, for example). The main window’s title bar contains the name 
of the application, but no document name. The main window also contains 
the application’s menus. The menus may vary according to the type of 
document the active child window contains. For example, if the user 
moves from a child window that contains a spreadsheet document to a 
child window that contains a chart document, spreadsheet-specific menus 
may be replaced with chart-specific menus. The menus can be selected and 
menu items chosen regardless of which of the application’s windows is 
active. 
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The last entry on the menu bar is the Window menu. The commands in 
this menu include any commands that are used to manage child windows 
and a list of the different child-window names. The main window’s name is 
also included on the Window menu. The user can choose from the list of 
window titles to select the next active window and bring it to the front. 
The following figure shows a typical Window menu: 
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Figure 13.2 Window Menu 


Commands that are used to manage child windows should be placed as a 
group in the Window menu before the list of window names and above a 
line separator. Such commands might include an Arrange command to 
organize the placement and size of the child windows within the main 
window. The resulting arrangement could be either overlapped or tiled, 
depending on the application. The previous illustration, Figure 13.2, 
shows a Window menu that contains the Arrange command. 


In some applications, commands that are specific to the main window may 
be available only when that window is selected. Therefore, the main win- 
dow’s name is the first window title listed in the Window menu to make it 
easy to select regardless of the number of child windows. Applications that 
do not have commands that are specific to the main window may omit this 
menu item. 


Each window title on the Window menu is preceded by a digit that serves 
as the menu item’s mnemonic. This gives direct and consistent keyboard 
access to all menu items regardless of the names of the child windows. The 
application can use letters as the mnemonics if single-digit identifiers are 
unavailable. 


102 


Multiple-Document Interface 


13.3 The Child Window 


The title bar of each child window contains the name of the document and 
a Control menu, but no other menus. If a single document is being viewed 
in more than one child window, a number is appended to the document 
name to distinguish between the windows, for example, “SAMPLE.TXT:1” 
and “SAMPLE. TXT:2.” 


The active child window is differentiated from other child windows by a 
change in the color or pattern of the title bar (in the same way that the 
active main window is differentiated from other main windows). When the 
application 1s active, the title bars of the main window and, if appropriate, 
the selected child window give active indications. 


Windows records the active child window when the user begins working 
with another application. Switching back to the application by using 
ALT+ESCAPE reactivates that child window as well as the main window. 


The Control-menu box in the child window’s title bar differs from the 
main window’s Control-menu box. A minus sign in the child window’s 
Control-menu box represents the key combination (ALT, MINUS) used to 
access the child window’s Control menu. The commands on the Control 
menu are the same for both the child window and the main window; how- 
ever, the application should modify the corresponding accelerators in the 
child window, replacing the ALT key with the CONTROL key (see the list 
included later in this eecteu). Any commands that are not appropriate are 
disabled (grayed). An example of a Control menu in a child window is 
shown in the following figure: 
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Figure 13.3 Child Window’s Control Menu 


Child windows should use the following key combinations to access 
Control-menu items: 


Key Action 

CONTROL-+F5 Invokes the Restore command. 
CONTROL+F7 Invokes the Move command. 
CONTROL+F8 Invokes the Size command. 
CONTROL+F9 Invokes the Minimize command. 
CONTROL-+F10 Invokes the Maximize command. 
CONTROL+F4 Invokes the Close command. 


The size and position of a child window are controlled by commands from 
the child window’s Control menu. These commands parallel functions pro- 
vided in the main window’s Control menu; however, the size and move- 
ment of the active child window are restricted to the size of the main win- 
dow. Child windows also can be moved and sized with the mouse just as 
main windows can. 


The Minimize command is usually disabled in a child window’s Control 
menu, but if the application can create an icon for its child windows, this 
command may be used. Icons that represent child windows are displayed 
within the main window. 


Choosing the Maximize command causes the document in the child win- 
dow to fill the main window. (Double-clicking the title bar of the child 
window is a mouse shortcut for choosing the Maximize command.) The 
main window itself does not change in size. The title bar of the child 
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Choosing the Maximize command causes the document in the child win- 
dow to fill the main window. (Double-clicking the title bar of the child 
window is a mouse shortcut for choosing the Maximize command.) The 
main window itself does not change in size. The title bar of the child win- 
dow “slides under” the menu bar of the main window, and the caption of 
the main window changes to include the name of the document. The child 
window’s Control menu is placed on the menu bar. (The main window’s 
Control menu controls the operation of the main window even when the 
child window is enlarged to its maximum size.) The following illustration 
shows a maximized child window with its Control menu displayed: 
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Figure 13.4 Maximized Child Window 


If the active child window is enlarged to its maximum size, switching to 
another child window will automatically enlarge that window to its max- 
imum size. This allows the user to quickly flip through documents. An 
application may choose to maximize the child window automatically as the 
default if there is only one open child window, such as when the user starts 
the application from the MS-DOS Executive window by using the docu- 
ment filename. Documents that were subsequently opened would take on 
the state of the active child window and, therefore, would be maximized if 
the previous working document were maximized. 


Selecting the Restore command from the child window’s Control menu 
restores the child window to its original size and location among the other 
child windows. 


The child window’s Close command destroys the child window after dis- 
playing a dialog box to confirm any required save operation for changes to 
the file. Double-clicking the child window’s Control-menu box is a mouse 
shortcut for choosing the Close command. 
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13.4 Moving Within the Interface 


The following key assignments are recommended for moving within the 


multiple-document interface: 


Key 


F6 


SHIFT+F6 


CONTROL-+F'6 


SHIFT+CONTROL+F6 
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Recommended Action 


Selects the next active subdivision of a win- 
dow (a child window within a document win- 
dow), moving clockwise. 


Selects the next active subdivision of a win- 
dow, moving counterclockwise. 


Selects the next active document window 
(a child window within the main window), 
moving from front to back. 


Selects the next active document window, 
moving from back to front. 


« 


cn cecreonace 


cnn ne re ee 


Index 


ze a ie ,18 
%% placeholder, 92 
~ (tilde), 60 


About... command, 24 
Accelerators 
ALT key, 29 
coding, 92 
CONTROL key, 29 
Control-menu commands, 30 
definition of, 29 
Edit-menu commands, 30 
function keys, 29 
guidelines, 29, 30 
help facility, 95 
international use, 89 
keynames, 29, 30 
SHIFT key, 29 
Active window 
input focus, 43, 50 , 
multiple-document interface, 46, 101, 
103 
selection highlighting, 35 
ALT key, 29, 44, 92 
ALT, MINUS, 103 
ALT, SPACEBAR, 44 
ALT+BACKSPACE, 30, 48 
ALT+ESCAPE, 44, 108 
ALT+F1, 46 
ALT+F2, 46 
ALT+F4, 30, 44 
ALT+F5, 30, 44 
ALT+F6, 44. 
ALT+F7, 30, 44 
ALT+F8, 30, 44 
ALT+F9, 30, 44 
ALT+F10, 30, 44 
ALT+mnemonic, 15 
ALT+mnemonie letter, 71 
ALT+SHIFT+TAB, 44 
ALT+TAB, 44 
ANSI character set, 89, 92 
AnsiToOem function, 89 
Application 
cooperation, 83 
international use, 89 
loading, 83 
names, 92 


Application (continued) 
quitting, 20, 24 
Application-modal dialog box, 65, 76 
Arrange Command, 102 
Arrow pointer, 55 
ASCII character set, 89 


BACKSPACE key, 30, 37, 48 
Bitmap, 89 
Box 


check, 66, 71 
Control menu, 5, 103 
dialog See Dialog box 
group, 72 
list, 61, 66 
Maximize, 5 
Minimize, 5 
Button 
Cancel, 69, 77 
default, 68 
grayed, 69 
No, 69, 77 
OK, 69, 77 
push See Push button 
radio, 66, 67, 71, 72 
required, 69 
Retry, 77 
Yes, 69, 77 


Cancel push button, 69, 77 
Caption 
child window, 103 
main window, 6 
message box, 76 
Caret, 37 
Caution message, 75, 78 
Character selection, 36, 37 
Character sets, 89 
Check box, 66, 69, 71 
Checkmark, 17, 18 
Child window See also Multiple- 
document interface 
control menu, 49 
definition of, 10 
dialog box See Dialog box 
flashing message, 77 
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Child window See also Multiple- 
document interface (continued) 
illustration of, 10, 101 
in multiple-document interface 
Contro! menu, 103-105 
icon, 104 
illustration of, 101 
menus, 101 
size, 104 
title bar, 103 
international use, 91 
keyboard interface, 46, 49 
strings, 91 
Clear command, 23, 31 
Chent area 
definition of, 7 
output, 7 
parent window, 10, 101 
scrolling See Scrolling 
size, 7, 101 
Clipboard 
Edit-menu commands, 23 
selection for, 35 
Clipped output, 7, 8 
Clock icon, 6 
Close command 
main window, 19, 20, 24, 30 
child window, 104-105 
Code 
discardable segments, 83 
source, 89, 91 
swapping, 83 
Color, 85 
Command button See Push button 
Command 
About..., 24 
accelerators, 29-31 
Arrange, 102 
button See Push button 
Clear, 23, 31 
Close 
main window, 19, 20, 24, 30 
child window, 104-105 
Copy, 23, 30 
Country Settings, 90 
Cut, 23, 30 
description of, 7 
dialog box use, 65, 68, 69 
disabled, 18 
Exit, 20, 24 
extended, 17, 18 
grayed, 18 
in File menu, 20-22 
in Control menu, 19-20, 30 See also 
Control menu 
in Edit menu, 23, 30-31 
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Command (continued) 

in menu, 15, 17 

independent, 17 

input requests, 65 

Maximize, 19, 30, 104 

Minimize, 19, 30, 104 

Move, 19, 30, 104 

mutually exclusive, 18 

New, 20, 21, 78 

Open..., 20, 21, 78 

Paste, 23, 31 

Print, 79 

Restore, 19, 30, 104, 105 

Save, 20, 22 

Save As..., 21, 22, 78 

selection for, 23, 35 

Size, 19, 30, 104 

toggle, 16, 17, 18 

Undo, 23, 30 
Context-sensitive help, 97 
CONTROL key, 29, 43 
CONTROL-+DELETE, 48 
CONTROL+DIRECTION, 49 
CONTROL-+END, 49 
CONTROL+ESCAPE, 44 
CONTROL+F4, 49 
CONTROL+F5, 49 
CONTROL+F6, 43, 46 
CONTROL+F7, 49 
CONTROL+F8, 49 
CONTROL+F9, 49 
CONTROL+F10, 49 
CONTROL+HOME, 48 
CONTROL+INSERT, 30, 48 
CONTROL+mouse movement, 54 
CONTROL+PAGE DOWN, 9, 48 
CONTROL+PAGE UP, 9, 48 
CONTROL+SHIFT+DIRECTION, 49 
Control menu 

About... command, 24-25 

accelerators, 30 

child window, 49, 104 

Close command, 20, 21 

disabled item, 19 

guidelines, 19 

illustration of, 19 

in dialog box, 65, 66 

keyboard selection, 44 

main window, 5 | 

multiple-document interface, 103 oa 
Control-menu box, 5, 103 
Controls 

check box, 66, 69 

default, 68-69, 70 

design, 71 

edit control, 61, 66, 72 


Controls continued) 
grayed labels, 67 
help facility, 95 
illustration of, 67 
inactive, 67 
labels, 67 
list box, 61-62, 66 
message box, 76 
mnemonics, 67, 71 
moving between, 70 
multiple, 69 
names, 67 
push button See Push button 
radio button, 66, 69, 71, 72 
required buttons, 69 
static-control label, 68, 72 
Conversion program, character sets, 89 
Cooperation between applications, 33 
Copy command, 23, 30 
Country settings, 90 
CPU sharing, 83 
Cut command, 23, 30 


Data files, 20 See also File and 
Filename 
Dead-air operations, 84 
Default 
controls, 68-69, 70, 77 
filename extension, 59 
maximizing child window, 105 
proposed filename, 61 
Delayed operation, 84 
DELETE key, 31, 37, 48 
Device error, 77 
Dialog box See also Message box 
About... command, 24 
appearance, 66, 71-72 
application-modal, 65 
canceling, 69, 70 
caption, 66 
check box, 66 
Close command, 21 
Control menu, 65, 66 
controls See Controls 
default button, 68 
edit control, 61, 66 
Exit command, 24 
extended commands, 17, 18 
font, 70 
framed border, 66 
guidelines, 65 
help facility, 95 
Help Information, 97 
Help Topics, 96 
ilustrations of, 78 


Index 


Dialog box See also Message box 
(continued) 
input focus, 68, 69, 70 
international use, 89, 91 
keyboard interface, 45, 68-71 
list box, 61, 66 
menu bar, 66 
message box See Message box 
mnemonics, 67, 71 
modal, 65, 68, 75 
modeless, 65 
multiple controls, 69 
multiple-document interface, 105 
New command, 21 
Open... command, 21 
prompting for filename, 61, 62 
push button, See Push button 
radio button, 66, 69, 71, 72 
Save As... command, 22, 59 
Save command, 20, 59 
scrolling, 71 
size, 70 
static-control label, 72 
strings, 91 
system-modal, 66, 76 
title bar, 66 
types, 65 
Direct access See Mnemonics 
DIRECTION keys, 45, 47, 49, 71, 72 
Directory 
list box, 61-62 
prompting for name, 61 
temporary files, 60 
Disabled menu item, 18, 19, 24, 66 
Disabled push button, 69 
Discontinuous selection, 39, 54. 
Disk-drive list box, 60-61 
Document window See also Child 
window 
caption, 103 
definition of, 11 
moving input focus, 43 


Edit control, 61, 66, 72 
Edit menu, 23-24, 30 
Editing selections, 37, 46-49 
Ellipsis (...), 18 
END key, 49 
English measurements, 92 
ENTER key, 47, 69, 70, 77 
Error 
device, 77 
flashing message, 77 
messages, 75, 76, 80 
system, 66, 76, 5 
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Error (continued 

system beep, 76 
ESCAPE key, 69, 70, 77, 97 
Exit command, 20, 24 
Extended command, 17, 18 
Extended selection, 36, 37, 54 
Extension, filename, 59 


Fl key, 31, 46 

F2 key, 46 

F4 key, 30, 44, 49 

F5 key, 30, 44, 49 

F6 key, 43, 46 

F7 key, 30, 44, 49 

F8 key, 30, 44, 49 

F9 key, 30, 44, 49 

F10 key, 30, 44, 49 

F11 key, 46 

F12 key, 46 

File See also Filename 
international use, 91-92 
naming, 6, 78 
overwrite message, 78 
prompting for name, 61 
resource, 89, 91, 92 
saving, 59, 78 
temporary, 60 
system failure, 85 
use, So 
win.ini, 59, 90 

File menu, 20-22, 78-79 

Filename 
default extension, 59 
extension, 59, 60 
guidelines, 59 
in title bar, 6-7 
international use, 92 
null extension, 60 
pathname, 59 
prompting for, 61 
proposed default, 61 
searching PATH, 59 
temporary files, 60 

Fixed-memory objects, 83 

Fixed-size window, 5 

Flashing 
bar, 37 
bitmap, 37 
caret, 37 
error message, 77 
icon, 77, 83 
message box, 77 
title bar, 77, 83 

Font, 70 

Formats, 90 
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Function keys See also specific key 
acclerators, 29-31 
recommended use, 43 
help facility, 95 

Functions 
AnsiloOem, 89 a 
GetTempFileName, 60 
OemToAnsi, 89 


GetTempFileName function, 60 
Graphics See Non-text selection 
Grayed menu item, 18, 19, 24, 66 
Grayed push button, 69 
Group box, 72 
Guidelines 
About... command, 24 
accelerators, 29, 30 
application, 1 
child window, 10, 103 
Control menu, 19 
controls, 66, 67, 69, 71 
dialog box, 65-66 See also herein 
message box 
disabled item, 18, 19 
Edit menu, 23 
File menu, 20, 21 
filename, 59, 60, 61 
help facility, 95 
highlighting, 35 
icon, 6 
input focus, 50, 55 
international use, 89 
keyboard interface, 43, 46 
main window, 5 
menu, 15 
menu item, 16 
message box, 75-76 
mouse interface, 53, 54, 55 
multiple-document interface, 101 
non-text selection, 38, 46, 54 
push button, 69, 71 
reserved keys, 44 
scrolling, 8 
selection, 35, 36, 37 
shared environment, 83 
split window, 10 
temporary file, 60 
text selection, 46, 54 
toggle command, 17 
translating, 89 


Help facility 
context-sensitive help, 97 
FI key, 31, 95 


Help facility (continued) 
general help, 96 
Help Information dialog box, 97 
Help mode, 97 
Help Topics dialog box, 96 
menu, 95 
push-button controls, 95 
Hexadecimal number, 60 
Highhghting, 35, 37, 38 
HOME key, 48 
Hourglass pointer, 55, 84 


J-beam pointer, 55 
Icon 
child window, 104 
Clock, 6 
flashing, 77 
international use, 89 
main window, 6 
message box, 75 
updating output, 6 
Inactive See Grayed 
Initilization requirements, 83 
Input focus 
delay in operation, 84 
dialog box, 68, 69, 70 
keyboard interface, 50 
mouse interface, 55 
Insertion-point selection, 36, 37 
INSERT key, 48 
Insert /replace mode, 48 
Interface 
keyboard See Keyboard interface 
mouse See Mouse interface 
multiple-document See Multiple- 
document interface 
user, 1, 5 
International use 
application names, 92 
filenames, 92 
formats, 90 
keyboard interface, 89, 92 
measurements, 92 
resource file, 89 
settings, 90 
sorting, 92 
Item selection, 38, 46-49 
Items in amenu See Menu item 


Keyboard interface See also spectfic 


key 
built-in, 43 
control selection, 68, 71 
Control-menu selection, 44 


Index 


Keyboard interface See also specific 
key (continued 

dialog box, 68, 71 

guidelines, 46 

help facility, 95, 96, 97 

input focus, 50 

international use, 89, 92 

menu names, 15 

message box, 77 

mnemonics 
dialog box, 67-68, 71 
menu item, 16, 20-21, 23, 24, 25 
menu name, 15 

moving input focus, 44 

multiple-document interface, 102, 

103, 104, 106 

recommended keys, 46-49 

reserved keys, 44-45 

scrolling, 8, 46-49 

selection, 35, 37, 46-49 

trapping input, 50 

Keys See also specific key and 

Keyboard interface 

international use, 89 

OEM-specific, 92 

recommended use, 46-49 

reserved for dialog box, 45 

reserved for menu, 45 

reserved for system, 44 

shortcut See Accelerator 


Labels on controls, 67 
Line selection, 36, 37 

Line separator, 16 

List. box, 61-62, 66-67 
Loading applications, 83 
Localizing applications, 89 


Main window 
caption, 6 
child See Child window 
client area See Client area 
Control menu, 5 
creation of, 5 
format, 5 
guidelines, 5 
icon, 6 
illustration of, 5, 7 
Maximize box, 5 
menu bar, 5 
Minimize box, 5 
multiple-document interface, 101 
output See Output 
scroll bar, 5 
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Main window (continued) 
scrolling See Scrolling 
split See Child window 
title bar, 6 
updating output See Output 
Maximize box, 5 
Maximize command, 30, 104 
Measurements, 92 
Memory use, 838, 84 
Menu bar 
definition of, 15 
dialog box, 66 
help facility, 95 
illustration of, 5, 15 
international use, 89 
main window, 5 
multiple-document interface, 101 
Menu item 
accelerators See Accelerators 
checkmark, 17 
commands, 17 See also individual 
command 
Control-menu commands, 19 
dialog-box use, 17, 18, 78-79 
disabled, 18-19 
Edit-menu commands, 23 
extended commands, 17, 18 
File-menu commands, 20-21 
grayed, 18-19 
illustration of, 16 
international use, 89 
keyboard interface, 43 
message-box use, 78-79 
names, 16, 18 
reserved keys, 45 
state setters, 17 
toggle command, 16, 17, 18 
types, 16 
Menu mode, 44 
Menu names, 15 
Menu 
accelerators See Accelerators 
bar See Menu bar 
checkmark See Toggle command 
commands, 15 See also individual 
command 
Control See Control menu 
definition of, 15 
disabled item, 18, 19 
Edit, 23-24, 30 
File, 20-22, 78-79 
help facility, 95 
illustration of, 16 
item See Menu item 
keyboard interface, 438, 45 
mode, 44 


112 


Menu (continued) 
names, 15 
reserved keys, 45 
strings, 91 
Window, 102 
Message box 
application-modal, 76 
captions, 76, 79 
caution, 75, 78 
default push button, 77 
definition of, 75 
flashing, 77 
guidelines, 75, 79 
illustrations of, 78 
international use, 91 
keyboard interface, 77 
names, 76 
note, 75 
print, 79 
push buttons, 76-77 
save, 78 
status, 75 
stop, 75 
system-modal, 76 
text guidelines, 79 
title bar, 76 
types, 75-76 
warning, 75, 76, 78 
Messages 
caution, 75, 78 
error, 75-76, 80 
guidelines, 80 
international use, 91 
note, 75 
overwrite, 78 
print, 79 
save, 78 
status, 75 
stop, 75 
system beep, 76 
warning, 75, 78 
names, 79 
Metric measurements, 92 
Minimize box, 5 
Minimize command, 30, 104 
MINUS key, 103 
Mnemonics 
definition of, 15 
dialog box, 67, 71 
menu item, 16 
menu name, 15 
multiple-document interface, 102 
Modal dialog box, 65, 68, 75 
Mode 
help, 97 
insert /replace, 48 


Mode (continued) 
menu, 44 
Modeless dialog box, 65 
Monochrome, 85 
Mouse interface 
built-in, 53 
guidelines, 53 
help facility, 95, 96 
input capture, 55 
multiple-document interface, 104, 
105 
pointers, 55 
scrolling, 9 
selecting, 35, 37, 54 
terms, 53 
Move command, 30, 104 
Multiple-document interface 
active window, 103 
child window 
Control menu, 103-105 
icon, 104 
illustration of, 101 
menus, 101 
size, 104 
title bar, 103 
Control menu, 103 
definition of, 11, 101 
dialog box, 105 
document window See Document 
window 
illustration of, 101 
keyboard interface, 48, 49, 104, 105 
main window, 101 
menu bar, 101 
mnemonics, 102 
mouse interface, 104, 105 
moving input focus, 46 
moving within, 105 
split window, 10 
subdivision of awindow See 
Subdivision of a window 


Naming 
accelerators, 29, 30 
applications, 6, 92 
controls, 67 
edit controls, 72 
files See Filename 
menu items, 16 
menus, 15 
message boxes, 76, 79 
push buttons, 71 
windows, 6 

New command, 20, 78 

Next push button, 97 


Index 


No push button, 69, 77 

Non-text selection 
definition of, 35 
discontinuous, 39 
enclosing rectangle, 35, 38 
extended, 38 
guidelines, 38 
highlighting, 35, 38 
item, 38 
keyboard interface, 46 
mouse interface, 54 
region, 38 

Note message, 75 


OemTodAnsi function, 89 
OEM-specific keys, 92 
OK button, 69, 77 
On-line help, 95 
Open... command, 20, 78 
Operation 

dead air, 84 

delay in, 84 

disk, 85 

time critical, 83 
Option button, 66 
Output 

clipped, 7 

illustration of, 8 

in child window, 10 

in client area, 7 

in split screen, 10 

scrolling See Scrolling 

updating client area, 7 

updating icon, 6 
Overlapping window, 5 
Overwrite message, 78 


PAGE DOWN key, 9, 48 
PAGE UP key, 9, 48. 
Parent window See also Multiple- 
document interface 

Close command, 20 

definition of, 10 

illustration of, 10, 101 
Paste command, 23, 31 
PATH variable, 59 
Placeholder, %%, 92 
Pointer 

arrow, 00 

hourglass, 84 

I-beam, 55 

question mark, 97 
Previous push button, 97 
Print command, 79 
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Print message, 79 
Program 
conversion, 89 
Setup, 90 
Punctuation selection, 36 
Push button 
Cancel, 69, 77 
choosing, 69 
default, 68-69 
description of, 66 
design, 71 
disabled, 67, 69 
Help, 95 
in message boxes, 76 
inactive, 67, 69 
Next, 97 
No, 69, 77 
OK, 69, 77 
Previous, 97 
required, 69 
Retry, 77 
Topics, 97 
Yes, 69, 77 


Question-mark pointer, 97 
Quitting applications, 20, 24 


Radio button, 66-67, 69, 72 
RAM use, 84 
Region selection, 38 
Reserved keys 

dialog box, 45 

menu, 45 

system, 44 
Resource file, 89, 91, 92 


Restore command, 30, 104, 105 


Retry push button, 77 
Reverse video, 35, 38 
Rules See Guidelines 


Save As... command, 21, 22, 78 


Save command, 20, 22 
Save message, 78 
Screen display, $3, 85 
Scroll arrows, 9 
Scroll bar 

dialog box, 71 

illustration of, 9 

main window, 5 

mouse interface, 9 
Scroll box, 9 
Scrolling 

clipped output, 7 
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Scrolling (continued) 

definition of, 8 

dialog box, 71 

guidelines, 3 

keyboard interface, 8, 48 

mouse interface, 9 
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About This Manual 


Purpose 


This manual describes TIFF, the Tag Image File Format. It covers the purpose of 
TIFF, how each of the fields work, and how software can be developed that can read 
and write TIFF files while maintaining industry compatability. This document is not in- 
tended to replace the official TIFF file specification, but is intended as a useful sup- 
plement. 


This document is provided courtesy of Hewlett-Packard Company, Inc. HP is an inde- 
pendent software vendor supporting TIFF. HP has developed software for reading, 
writing, decompressing, and compressing TIFF files. This source code is included in 
the Microsoft Windows Software Development Kit. Additional source code is avail- 
able to independent software vendors via a license agreement. If you would like to 
learn more about this software and peripherals that support TIFF, please contact: 


Hewlett-Packard Company 
Greeley Division 

ISV Marketing Department 
700 71st Ave. 

Greeley, CO 80634 

(303) 350-4000 


Using This Manual 


This manual contains 7 chapters. Each section is briefly described below: 


Chapter 1 Provides an overview of TIFF. 

Chapter 2 Describes the structure of a TIFF file. 
Chapter 3 Provides sample TIFF image files. 

Chapter 4 Describes each of the TIFF tags. 

Chapter 5 Tells how to develop TIFF software. 
Chapter 6 Describes how TIFF is administered. 
Chapter 7 Describes miscellaneous TIFF information. 
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An Overview of the Tag Image File Format 
1.1 Introduction 


Desktop Publishing is an exciting new computer application that will allow people to 
quickly produce attractive documents. One very important technique used in desktop 
publishing is to merge line-art and photographs with text. 


This document describes TIFF, the Tag Image File Format. This is a new file format 
that assists in incorporating line-art, photographs, and other raster images into docu- 
ments via desktop publishing application programs. 


There are a number of different ways that images like line-art and photographs are 
brought into a desktop publishing application program. The most common way is to 
have a specialized application program collect or produce an image. Then, image in- 
formation is converted into a file and saved on a disk. Finally, a desktop application 
program can read the file containing the image information, combine it with other text 
files, and allow the user to compose a publication in an attractive and artistic fashion. 


Another way to bring images into a desktop publishing program is to have the 
program directly interact with a scanner, a mouse, or a camera to produce the image 
while doing page layout. This is much simpler for the user since he is able to quickly 
iterate between the tasks of drawing or scanning and page composition. However, due 
to code space limitations and other considerations, most desktop publishing packages 
don’t include functions that control scanners or permit a user to make elaborate draw- 
ings. 


Thus, a key part of desktop publishing is the communication of information between 
specialized application programs. As shown in figure 1.1, there can be many different 
applications working together to produce a final document. They all communicate via 
different files of information. 


The organization and structure of the files used in desktop publishing becomes an im- 
portant consideration. The file format should be structured to support the necessary 
features needed by image-producing devices. Secondly, desktop publishing applica- 
tions are easier to develop if only a few different file formats are required to support 
the specialized application programs. 


The Tag Image File Format (TIFF) is a new file format that meets both of these condi- 
tions. TIFF provides features that support most input device requirements, such as 
scanners, paint programs, and cameras. TIFF also contains features not found in 
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other file formats, such as support for a variety of data compression techniques, and 
flexibility to add new features easily and in a controlled fashion. 


TIFF is rapidly becoming the accepted industry standard file format for desktop 
publishing images. This standard is equally applicable for both the IBM and Apple en- 
vironments. Many well-known companies in the desktop publishing arena have an- 
nounced support for this format, and the list continues to grow. 


It is very important for desktop publishing application developers to seriously con- 
sider supporting this format. Again, this is because it provides many advantages over 
either designing another file format or using one of the existing paint program file for- 
mats. 


An Overview of the Tag Image File Format 


There are two purposes of this document. First, it will explain TIFF so that an in- 
formed decision can be made about whether or not to support the standard. Secondly, 


this document will assist a programmer in developing software to read and write TIFF 
files. 


Note that this document serves as a supplement and does not replace the official 
TIFF document as managed by Microsoft. 


1.2 A Comparison Between TIFF and Other File Formats 


Traditional painting program file formats use a fixed-format organization, as shown in 
figure 1.2. The organization and location of each value is known prior to reading the 
file. Thus, the X resolution information of this file is always stored at byte locations 2 
and 3. 


0 
2 
4 
6 
8 
10 


REVISION # 
X RESOLUTION 


Y RESOLUTION 


H PIXELS 
V PIXELS 


COLOR PLANE 
al 


Figure 1.2 


TIFF employs a different structure based on tagged information. This structure is 
commonly used in data base design. Figure 1.3 shows a diagram of a few values from a 
TIFF file. Each tag of a TIFF file is really a header that completely describes informa- 
tion contained elsewhere in the file. For example, the first field in a tag specifies the 
name of the tag information. The tag also contains other fields that describe both the 
length and size of the described information. Finally, there is a pointer to the actual 
values described by the tag. 
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To read the X resolution, the "X resolution" tag must first be located by reading 
through each tag description field. Then, the actual X resolution is found at another 
location. 


Each different kind of information about an image requires a unique tag. For ex- 
ample, there is a tag for the X resolution of the image. There are other tags for the Y 
resolution and data compression methods used. 


Another difference between paint file formats and TIFF is that TIFF has additional 
information that usually doesn’t appear in paint file formats. For example, TIFF 
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provides support for different compression schemes, multiple image resolutions, and 
different image types such as binary, gray scale, and color. 


1.3 Advantages and Disadvantages of TIFF 


Although the tag structure of TIFF may seem to add an unnecessary layer of over- 
head, it provides a key advantage over a fixed-file format. It is very easy to add new 
tags to the format without requiring all supporting software to be re-written. For ex- 
ample, one application writer may want to add to the format a "date of creation" tag 
for an image. This tag can be included with the other tags when the file format is writ- 
ten. Other applications that read TIFF files don’t need to be re-written unless they 
want to make use of this new tag that describes the date of creation. They can in most 
cases safely ignore unrecognized tags, like the "date of creation". 


In contrast, a fixed-position organization usually requires a rewrite of all application 
programs each time a new field is added. The rewrite is needed whether or not all ap- 
plications want to make use of the new information. 


Certain changes made in the future can affect an existing application program. For ex- 
ample, if some additional modifications must be made to support a new kind of raster 
data, an existing application probably won’t be able to properly interpret the bit-map 
image. In defining TIFF, most unique raster data types such as gray-scale and color 
have been defined to make the file format as flexible as possible. 


Another advantage of TIFF is that it can meet a variety of imaging needs. TIFF files 
contain tags that describe not only the height and width of the image, but also contain 
resolution information, support gray scale and color data, and allow for public and 
private data compression schemes. 


Third, TIFF is quickly becoming an industry standard. A number of leaders in the 
DTP arena have announced public support for TIFF for both Apple and IBM applica- 
tions programs. 


There are some disadvantages to TIFF as well that must be intelligently managed. The 
flexibility of TIFF poses a problem. There isn’t one "standard" TIFF file. Different ven- 
dors can elect to support different tag fields of TIFF. There is no guarantee that a 
given DTP program will read any given collection of TIFF tags. Thus, there is a strong 
requirement for additional coordination beyond "conforming" to the TIFF document. 
To effectively manage this disadvantage, there are several recommendations outlined 
later in this document. If these recommendations are followed, then compatibility 
should be relatively easy to achieve. 
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Another disadvantage to TIFF is that it is more complicated to understand and imple- 
ment than other fixed-format file organizations. The intent of this document and the 
source code available from HP and Microsoft is to help in quickly understanding and 
implementing TIFF. 


Finally, there is additional software overhead necessary to read and write TIFF files 
compared to reading and writing other file formats. However, this extra overhead 1s a 
small percentage of the code requirements for most applications. 


1.4 Who Is Supporting TIFF Currently 


A number of companies have publicly announced support of TIFF. These include: 


Aldus 

Microsoft 
Hewlett-Packard 

Dest 

DataCopy 

Microtek 

Media Cybernetics 
New Image Technology 
Software Publishing 


Many other companies have copies of the TIFF standard and are seriously consider- 
ing support. 


1.5 What This Document Will Cover 


Chapter 2 of this document will discuss the general structure of a TIFF file. Then, 
Chapter 3 will provide some small sample files that demonstrate how to read and 
write TIFF files. Chapter 4 describes the details of the format including a description 
of each of the tags. Chapter 5 includes implementation notes and suggestions useful 
when designing software to read and/or write TIFF files. Chapter 6 describes how 
TIFF is maintained. Finally, chapter 7 includes a TIFF tag summary sheet, informa- 
tion on recommended values for TIFF files, and a TIFF worksheet. 
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The General Structure of a TIFF file 


2.1 Introduction 


It is helpful when learning how TIFF works to take a close look at the overall organiza- 
tion of a TIFF file. There are really four separate sections of a TIFF file as shown in 
Figure 2.1. These sections include the header, the directory, tags and their associated 
data within the directory, and finally the bitmap image data. 


4 
BIT-MAP 
IMAGE 


eee 


Figure 2.1 


Each of these sections performs a different function. In general, the header describes 
overall interpretation information for the entire TIFF file. For example, the header in- 
cludes data about the order of bytes and the revision number. 


The directory section describes everything necessary to make use of the associated bit- 
map of image data. A directory consists of tags and a pointer to the next directory (if 
any). TIFF allows for multiple directories in a single file. Each directory refers to a 
separate bitmap of information. Multiple directories and bitmaps can be used to store 
a full-resolution image for printing and a second reduced-resolution bitmap for dis- 
play purposes. It can also be used to store separate image pages of a multi-page FAX 
transmission document. 


The tags contained in a directory are the third section of a TIFF file. Each tag 
describes some aspect about the bitmap, such as the X and Y resolution. The entire 
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group of tags within a directory conveys all the needed information to completely 
describe the bitmap of image data. Then, this data can be appropriately interpreted 
and displayed or printed as required. 


Finally, the bitmap image is the fourth section of a TIFF file. This section consists of 
binary data that is organized and interpreted according to the tag information listed 
in the associated directory. 


2.2 Details of the Header Section 


The header section is shown in figure 2.2. This is the first information that appears in 
a TIFF file. It is an important structure to read first since it describes the order in 
which bytes appear in the rest of the TIFF header. There are two byte orders sup- 
ported in TIFF files. The byte order can be either the most significant byte followed 
by the least significant byte (68000 processor based), or it could be least significant 
byte followed by the most significant byte (8086 processor based). All the remaining 
information in the TIFF header will adhere to this byte order convention. 


The byte order is indicated by bytes 0 and 1 both being ASCII I’s for INTEL format, 


0 BYTE ORDER 
2 VERSION # 


FIRST DIRECTORY 


Figure 2,2 


or both being ASCII M’s for Motorola format. Thus, the header can be read by 
software running on either kind of processor since it will make little difference which 
byte of the byte order fields is read first. 
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The header also includes a TIFF version number, and a pointer to the first directory 
entry. Note that every pointer in a TIFF file is referenced with respect to the begin- 
ning of the file. 


Thus, the header needs to be read first and is the key for interpreting the rest of the 


TIFF file. It contains the only postonal information in the entire file. The rest of the 
information is pointer-based. 


2.3 Details of the Directory 


A directory consists of 3 parts as shown in figure 2.3. The first two bytes of the direc- 
tory contains an entry count. This entry describes how many different tags appear in 
the directory. Next, there are the actual 12-byte tags that describe the bitmap informa- 


ENTRY COUNT 


A+2 TAG 0 
A+ 14 * 
A+2+ 12N 
A+ 14+ 12N OFFSET TO 


NEXT DIRECTORY 
((F ANY) 


TAG DATA 
NOT FITTING 
INA TAG 


Figure 2.3 


tion associated with this directory. Finally, there is an offset field that points to the 
next directory (if any) contained in the TIFF file. If there is no following directory, 
then this last portion of the directory contains zeros. 
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Note that the directory can go anywhere in the TIFF file, but should be on a word 
boundary. This last condition is provided to make it easy to read the tag values with 
standard software. 


The tags in the directory must be in ascending order. This is to make it easy for a 
TIFF reading application to determine whether or not a desired tag 1s present. 


2.4 Organization of Each Tag Entry 


The tags that are contained within each directory entry form the basis for the Tag 
Image File Format. A sample tag is shown in figure 2.4. As mentioned earlier, these 
describe how to interpret the associated bitmap of binary data. Each tag is 12 bytes 
long and has a regular structure. 


A TAG TYPE 
A+2 DATATYPE 


POINTER 


Figure 2.4 


The first two bytes of a tag entry describe the type of information associated with the 
tag. For example, a tag value of 282 (11AH) in these two bytes indicates that this tag 
describes the X resolution of the bitmap image. 


The next two bytes of a tag entry indicate the data type used to provide the tag infor- 
mation. | 
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There are five different data types supported. Their values and interpretations are as 
follows: 


1=Byte: 8-bit bytes. 
2= Ascii: 8-bit ASCII codes. 
3 = Short: 16-bit (two byte) unsigned integers. © 
4= Long: 32-bit (four byte) unsigned integers. 
5=Rational: | Two longs; the first is the numerator of 
a fraction, the second is the denominator of 
the fraction. 


For example, the data type for the X resolution tag is a rational number. Thus, for a 
300 dpi image the first four bytes would be set to 300 (the numerator) and the second 
four bytes would be set to 1 (the denominator). 


Normally there will be only one data type associated with any particular kind of tag. 
However, a few tags can have more than one data type possible. For example, the 
StripOffsets and RowsPerStrip tags can be either of data type short or long. Thus, 
TIFF reading software will need to carefully check the type field and interpret the 
length and data fields in the tag appropriately. These two tags have a default data type 
of long, which is the encouraged type to use for the widest amount of interchange. 


The next four bytes of a tag field contain the length of the information pointed to by 
the tag. The units of the length are the data type of the tag. For example, if the length 
field contains 16 and the data type field is set long, then the data pointed to by the tag 
will be 16 units of length x 4 bytes/unit or 64 bytes. 


ASCII length requires a special note. All ASCII information in TIFF files is ter- 
minated with the null character. Further, ASCII information is padded out past the 
null character to be an even number of bytes. However, extra padding information 
after the null character is not included in the length calculation. 


The last four bytes of a tag field can serve one of two purposes. They can either point 
to where the actual tag data (such as the resolution) is located, or they can be the ac- 
tual tag data. If the actual tag data will physically fit within the four bytes of the tag 
entry, then it will be placed there. Otherwise, the four bytes will represent the offset of 
the actual data with respect to the beginning of the TIFF file. 


This convention, which probably seems a bit complicated at first, is designed to save 


time and storage space. The reader and writer of a TIFF file won’t need to make an in- 
direct reference if the data will fit within the tag itself. However, the software that 
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reads and writes TIFF files must be designed to check where to place or where to find 
the start of the actual tag data. This can be done by seeing if the length of the tag infor- 
mation in bytes (found by multiplying the length field times the bytes per data type) is 
4 bytes or less and will fit within the tag area. 


Some examples will help illustrate this concept. Let’s first look at the resolution tag as 
described earlier. For this tag, the data type is rational, and the data length is 1 ration- 
al number. Since a rational number requires 8 bytes, then the rational fraction data 
will not fit in the tag field. In this case, the information in the last four bytes of the tag 
field will be a pointer (with respect to the beginning of the file) to the 8 bytes of 
resolution information. 


The ImageWidth tag, on the other hand, describes the width of the images in pixels. 
This tag has a short data type, and has a length of 1 unit. Thus, the width information 
will fit into the tag field itself, since it is two bytes in length. Note that this information 
will be left justified in the first two bytes of the pointer/data area. In other words, the 
very last two bytes of the Image Width tag field won’t contain any significant data. 


The tags have another interesting property. The tag values can either be public (which 
means that they appear in the official TIFF document), or they can be private. Public 
fields are carefully defined and described to all companies participating in the TIFF 
standard. Private fields are allocated to individual companies by the TIFF ad- 
ministrator to be used as desired by the individual companies. Private fields are 
generally used to cover features either not of general interest, or for proprietary fea- 
tures that only a few companies utilize. 


Although private fields sound attractive since they give some control over the stand- 
ard, their use is discouraged. Private fields undermine the purpose of an interchange 
standard. Their use also reduces the number of users that can read the file. However, 
private fields can be useful to control technology and provide a competitive advantage 
for a period of time. For example, if a proprietary compression technique is available, 
then a small number of vendors who know how to interpret the private field can share 
in the technology and have an advantage over other companies. 


Finally, the tags within a directory must be listed in ascending order of tag value. This 


is to make it quick for the reader of a TIFF file to see if the required tags are present, 
or to locate the desired tags. 


In summary, TIFF files consist of a header, one or more directories, tags within the 
directories, and one or more bitmaps of image data. These are combined together to 
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The General Structure of a TIFF file 


provide an effective structure that is flexible and easily extended to meet future re- 
quirements. 
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Chapter 3 
Sample TIFF Image Files 


3.1 
3.2 


3.3 


3.4 


3.0 


Introduction 21 

An 8066-format 10 pixel x 10 pixel 

Black and White TIFF Image 21 

A 68000-format 10 pixel x 10 pixel 

Black and White TIFF Image 25 

An 8086-format 10 pixel x 10 pixel CCITT/3 
Compressed Black and White TIFF Image 29 


An 8066-format 10 pixel x 10 pixel 
4 Bit Gray Seale TIFF Image 34 
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Sample TIFF Image Files 


3.1 Introduction 


This chapter contains four sample TIFF files. These include an 8086-format black and 
white image, a 68000-format black and white image, an 8086-format compressed black 
and white mage, and an 8086-format gray-scale image. The tags and values used are 
intended as models for industry compatibility. 


These files should be especially helpful when learning how to understand and make 
use of TIFF. 


3.2 An 8086-format 10 pixel x 10 pixel Black and White TIFF Image 


300 DPI Image 

BINARY (Line art) image 
No data compression 

8086 byte order 
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mmmeed | ried | 


PEPE LL TT 


bo 


2 


Tag # 


OFFH 
100H 
101H 
102H 
103H 
106H 
107H 
108H 
109H 
10AH 
10DH 
10EH 
1OFH 
110H 
111H 
112H 


Tag Name 


Subfile Type 
ImageWidth 
ImageLength 
BitsPerSample 
Compression 
PhotometricInterp. 
Thresholding 
CellWidth 
CellLength 
FillOrder 
DocumentName 
ImageDescription 
Make 

Model 

Strip Offsets 
Orientation 
SamplesPerPixel 
RowsPerStrip 
StripByteCounts 
MinSample Value 
MaxSample Value 
XResolution 
YResolution 
PlanarConfiguration 
PageName 
XPosition 
YPosition 
FreeOffsets 
FreeByteCounts 
GrayResponseUnit 
GrayResponseCurve 
Group3Options 
Group4Options 
Resolution Unit 
PageNumber 
ColorResponseUnit 


Value 
Value: 1 
Value:_ 10 
Value: 10 
Value: 1 
Value: 1 
Value: 1 
Value: 

Value: 

Value: 
Value: 1 
Value: 

ASCil: 

Ascil: 

ASCil: 
Value/Offset: Offset 
Value: 1 
Value: 1 
Value: 
Value/Offset: 
Value: O | 
Value:_ 1 
Value: 300 _ 
Value:_300__ 
Value: 1 
ASCil: 

Value: 

Value: 
Value/Offset: 
Value/Offset: 
Value: 
Value/Offset: 
Value: 

Value: 

Value: 

Value: 

Value: 


oo, 


Sample TIFF Image Files 


12DH ColorResponseCurves Value/Offset: 
File worksheet 
I. Header 
Offset Value 
000 49 Note byte order is INTEL format. 
001 49 
002 2A Version #42, Note byte reversal 
003 00 
004 08 Pointer to first directory 
005 00 
006 00 
007 00 
Il. Directory 
008 OF 15 tags in this directory 
009 00 
Offset Tag Type Length Value/Oftset 
Tag1 O0A FFOO 0300 01000000 0100 0000 (Subfile type) 
Tag2 016 0001 03 00 01000000 OA00 0000 (Image width 10 pixels) 
Tag3 022 0101 0300 01000000 O0A00 0000 (Image length 10 pixels) 
Tag4 Q2E 0201 0300 01000000 0100 0000 (1 bit per sample) 
Tag5 O3A 0301 03 00 01000000 0100 0000 (Packed data compression) 
Tag6 046 0601 0300 01000000 0000 0000 (Black is 1) 
Tag7 052 OAOL 03 00 01000000 0100 0000 (Filled MSB to LSB) 
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Tag 8 

Tag 9 

Tag 10 
Tag 11 
Tag 12 
Tag 13 
Tag 14 


Tag 15 


O5E 


06A 


076 


082 


O8E 


09A 


0A6 


OB2 


11 01 


12 01 


1501 


18 01 


19 01 


End of directory 


III. 


IV. 
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BE 


04 00 


03 00 


03 00 


03 00 


03 00 


OS 00 


Q5 00 


03 00 


01 00 00 00 


01 00 00 00 


01 00 00 00 


01 00 00 00 


01 00 00 00 


01 00 00 00 


01 00 00 00 


01 00 00 00 


D200 0000 (Offset to raster data) 
0100 0000 (Normal orientation) 
0100 0000 (1 sample/pixel) 

00 00 0000 (Min value is 0) 

0100 0000 (Max value is 1) 

C2 000000 (Offset to X resolution) 
CA 000000 (Offset to Y resolution) 


0100 0000 (Planar config is normal) 


00 000000 (no more directories) 


Extended tag information (as needed) 


C2 


2C 01 00 00 
CA 2C01 0000 


01 00 00 00 (300 dpi X resolution) 
01.00 00 00 (300 dpi Y resolution) 


Raster data (as needed) 


FFCO 
FFCO 
OCOO0 
0CO0O0 
O0COO0 
QCO0 
O0CO0O 
0CO0 
0CO0 
O0CO00 


(10 black pixels) 
(10 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 


V. Strip offset pointers (as needed) 


None needed. 


VI. Strip byte counts (as needed) 


None needed. 


File is E6 bytes long. 


Sample TIFF Image Files 


3.3 A 68000-format 10 pixel x 10 pixel Black and White TIFF Image 


[| 
a 
c 
| 


PE 
| tt} tt 
|i: tf] | i 
| {ttt | | ie 


| || | i 
|| |i | tT ie 
-| tii tt | il 


ERGERREM 
jij ttt) | i 


ee 
i 
oeeeeeeen 


300 DPI Image 

BINARY (Line art) image 
No data compression 
68000 byte order 
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Baas 
aa 


PEEP Drrrre 


ho 
ON 


Hex 


OFFH 
100H 
101H 
102H 
103H 
106H 
107H 
108H 
109H 
10AH 
10DH 
10EH 
10FH 
110H 
111H 
112H 
115H 
116H 
117H 
118H 
119H 
11AH 
11BH 
11CH 
11DH 
11EH 
11FH 
120H 
121H 
122H 
123H 
124H 
125H 
128H 
129H 
12CH 
12DH 


Name 


SubfileType 
ImageWidth 
ImageLength 
BitsPerSample 
Compression 
Photometriclnterp. 
Thresholding 
CellWidth 
CellLength 
FillOrder 
Document name 
ImageDescription 
Make 

Model 

StripOffsets 
Orientation 
SamplesPerPixel 
RowsPerStrip 
StripByteCounts 
MinSample Value 
MaxSample Value 
XResolution 
YResolution 
PlanarConfiguration 
PageName 
XPosition 
YPosition 
FreeOffsets 
FreeByteCounts 
GrayResponseUnit 
GrayResponseCurve 
Group3Options 
Group4Options 
ResolutionUnit 
PageNumber 
ColorResponse Unit 
ColorResponseCurves 


Value 
Value: 1 
Value: 10 _ 
Value:_ 10 _ 
Value: 1 
Value: 1 | 
Value: 1 
Value: 

Value: 

Value: 
Value: 1 
Value: 

ASCil: 

Ascii: 

Ascii: 
Value/Offset:Offset 
Value: 1 
Value: 1 
Value: 
Value/Offset: 
Value: O | 
Value: 1 
Value: 300 _ 
Value:_300__ 
Value: 1 _ 
ASCii: 

Value: 

Value: 
Value/Offset: 
Value/Offset:_ 
Value: 
Value/Offset: 
Value: 

Value: 

Value: 

Value: 

Value: 
Value/Offset: 


File worksheet 


1 


YW. 


Tag 1 
Tag 2 
Tag 3 
Tag 4 
Tag 5 
Tag 6 
Tag 7 


Tag 8 


Header 


Offset Value 


000 
001 
002 
003 
004 
005 
006 
007 


Directory 


008 
009 


00 
OF 


Offset Tag 


00A 


016 


022 


Q2E 


03A 


046 


Q52 


OSE 


00 FF 


01 00 


01 01 


01 02 


01 03 


01 06 


O10A 


01 11 


Sample TIFF Image Files 


Note byte order is Motorola format. 


Version #42, Note byte order 


Pointer to first directory 


15 tags in this directory 


Type 
00 03 
00 03 
00 03 
00 03 
00 03 
00 03 
00 03 


00 04 


Length 

00 00 00 01 
00 00 00 01 
00 00 00 01 
00 00 00 01 
00 01 00 00 
00 00 00 01 
00 00 00 01 


00 00 00 01 


Value/Offset 

00.01 0000 (Subfile type) 

000A 0000 (Image width 10 pixels) 

00 0A 0000 (Image length 10 pixels) 
00 01 0000 (1 bit per sample) 

00 01 0000 (Packed data compression) 
00 00 00 00 (Black is 1) 

0001 0000 (Filled MSB to LSB) 


00 00 00 D2 (Offset to raster data) 
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Tag 9 

Tag 10 
Tag 11 
Tag 12 
Tag 13 
Tag 14 


Tag 15 


06A 


076 


082 


O8E 


09A 


OA6 


0OB2 


01 12 


01 15 


0118 


01 19 


011A 


01 1B 


01 1C 


End of directory 


III. 


IV. 


28 


BE 


00 03 


00 03 


00 03 


00 03 


00 OS 


00 05 


00 03 


00 00 00 O01 


00 00 00 01 


00 00 00 01 


00 00 00 01 


00 00 00 01 


00 00 00 01 


00 00 00 01 


00 01 00 00 (Normal orientation) 

00 01 0000 (1 sample/pixel) 

0000 0000 (Min value is 0) 

00 01 0000 (Max value is 1) 

00 00 00 C2 (Offset to X resolution) 
00 0000 CA (Offset to Y resolution) 


0001 0000 (Planar config is normal) 


00 000000 (no more directories) 


Extended tag information (as needed) 


C2 


00 00 01 2C 
CA 000001 2C 


00 00 00 01 (300 dpi X resolution) 
00 00 00 01 (300 dpi Y resolution) 


Raster data (as needed) 


FFCO 
FFCO 
0C00 
0C00 
0CO00 
O0CO00 
0CO0 
0CO00 
0CO00 
0CO00 


(10 black pixels) 
(10 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 


Sample TIFF Image Files 


Vz Strip offset pointers (as needed) 


None needed. 


VI. Strip byte counts (as needed) 


None needed. 


File is E6 bytes long. 


3.4 An 8086-format 10 pixel x 10 pixel CCITT/3 Compressed Black 
and White TIFF Image 


PID ai 
[| 
a 
a 
ied 
fe 
al 
al 
a 
nel 

300 DPI Image 

BINARY (Line art) image 

CCITT/3 data compression 

8086 byte order 
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ane 


| | | | | | | | la alles lca luallialeeltcalls 
aren 


e) 


0 


Name 


SubfileType 
ImageWidth 
ImageLength 
BitsPerSample 
Compression 
Photometriclunterp. 
Thresholding 
CellWidth 
CellLength 
FillOrder 
DocumentName 
ImageDescription 
Make 

Model 
StripOffsets 
Orientation 
SamplesPerPixel 
RowsPerStrip 
StripByteCounts 
MinSample Value 
MaxSample Value 
XResolution 
YResolution 
PlanarConfiguration 
PageName | 
XPosition 
YPosition 
FreeOffsets 
FreeByteCounts 
GrayResponseUnit 
GrayResponseCurve 
Group3Options 
Group4Options 


Value 


Value: 1 
Value: 10 _ 
Value: 10 _ 
Value: 1 
Value: 2 
Value: 1 
Value: 

Value: 

Value: 
Value: 1 
Value: 

Ascii: 

Ascu: 

Ascii: 
Value/Offset:Offset 
Value: 1 
Value: 1 
Value:__ 1 
Value/Offset:Offset 
Value: 0 
Value: 1 
Value: 300 _ 
Value: 300 __ 
Value: 1 
Ascii: 


~ Vaiue: 


Value: 
Value/Offset: 
Value/Offset: 
Value: 
Value/Offset: 
Value: 
Value: 


128H 
129H 
12CH 
12DH 


File worksheet 


I. 


II. 


Tag 1 
Tag 2 
Tag 3 
Tag 4 
Tag 5 


Tag 6 


Header 


Offset Value 


000 
001 
002 
003 
004 
005 
006 
007 


008 
009 


Offset 
O0A 
016 
022 
02E 
O3A 


046 


Directory 


11 
00 


Tag 

FF 00 
00 01 
0101 
02 01 
03 01 


06 O01 


ResolutionUnit 
PageNumber 
ColorResponse Unit Value: 
ColorResponseCurves Value/Offset: 


Sample TIFF Image Files 


Value: 
Value: 


Note byte order is INTEL format. 


Version #42, Note byte reversal 


Pointer to first directory 


17 tags in this directory 


Type 
03 00 
03 00 
03 00 
03 00 
03 00 


03 00 


Length 

01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 


01 00 00 00 


Value/Offset 

0100 0000 (Subfile type) 

0A 00 0000 (Image width 10 pixels) 
0A 00 0000 (Image length 10 pixels) 
0100 0000 (1 bit per sample) 

02.00 0000 (CCITT/3 compression) 


00 00 0000 (Black is 1; however doesn’t 
apply with CCITT/3) 
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Tag 7 

Tag 8 

Tag 9 

Tag 10 
Tag 11 
Tag 12 
Tag 13 
Tag 14 
Tag 15 
Tag 16 


Tag 17 


052 


OSE 


06A 


076 


082 


08 


09A 


OA6 


0B2 


OBE 


OCA 


0A 01 03 00 


1101 


12 01 


15 01 


16 01 


1701 


18 O01 


19 01 


1A 01 


1B 01 


1C 01 


End of directory 


Il. 


IV. 
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D6 


04 00 


03 00 


03 00 


04 00 


04 00 


03 00 


03 00 


05 00 


05 00 


03 00 


01 00 00 00 


0A 00 00 00 


01 00 00 00 


01 00 00 00 


01 00 00 00 


0A 00 00 00 


01 00 00 00 


01 00 00 00 


01 00 00 00 


01 00 00 00 


01 00 00 00 


0100 0000 (Filled MSB to LSB) 
FE 00 0000 (Offset to pointers) 
0100 0000 (Normal orientation) 
0100 0000 (1 sample/pixel) 

0100 0000 (1 row/strip) 

26 01 00 00 (Pointer to byte counts) 
0000 0000 (Min value is 0) 

0100 0000 (Max value is 1) 

DA 00 0000 (Offset to X resolution) 
E2 00 00 00 (Offset to Y resolution) 


0100 0000 (Planar config is normal) 


00 000000 (no more directories) 


Extended tag information (as needed) 


DA 2C0100 00 


R2 


Compressed raster data (as needed) 


EA = 3508 
EC 3508 
EE BECO 


2C 01 00 00 


(10 black pixels) 
(10 black pixels) 
(2 black pixels) 


010000 00 (300 dpi X resolution) 
01 00 00 00 (300 dpi Y resolution) 


FO 
F2 
F4 
F6 
F8 
FA 
FC 


BECO 
BECO 
BECO 
BECO 
BECO 
BECO 
BECO 


(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 
(2 black pixels) 


V. Strip offset pointers 


FE 
102 
106 


EA 00 00 00 
EC 00 00 00 
EE 00 00 00 
FO 00 00 00 
F2 00 00 00 
F4 00 00 00 
F6 00 00 00 
F8 00 00 00 
FA 00 00 00 
FC 00 00 00 


VI. Strip byte counts (as needed) 


126 
LA 
12E 
132 
136 
13A 
13E 
142 
146 
14A 


02 00 00 00 
02 00 00 00 
02 00 00 00 
02 00 00 00 
02 00 00 00 
02 00 00 00 
02 00 00 00 
02 00 00 00 
02 00 00 00 
Q2 00 00 00 


File is 14E bytes long. 


Sample TIFF Image Files 
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3.5 An 8086-format 10 pixel x 10 pixel 4 Bit Gray Scale TIFF Image 


300 DPI Image 
4 bit gray scale image 
No data compression 
8086 byte order 
Hex Name Value 
_ x OFFH SubfileType Value: 1 
_ x 100H ImageWidth Value: 10 _ 
_x_ 101H ImageLength Value: 10 | 
_ x 102H BitsPerSample Value: 4 
_ x 103H Compression Value: 1 
_ x 106H Photometriclnterp. Value: 1 
107H Thresholding Value: 
108H CelfWidth Value: 
109H CellLength Value: 
_x  10AH FillOrder Value: 1 
10DH DocumentName Value: 
10EH ImageDescription AScil: 
10FH Make AScil: 
110H Model Ascii: 


Sade 
aa 


Pee 
Peril 


PEEL | Lit 


File worksheet 


Lm! 


Header 


Offset Value 


000 
001 
002 
003 
004 
005 
006 
007 


StripOffsets 
Orientation 
SamplesPerPixel 
RowsPerStrip 
StripByteCounts 
MinSampleValue 
MaxSampleValue 
XResolution 
YResolution 
PlanarConfiguration 
PageName 
XPosition 
YPosition 
FreeOffsets 
FreeByteCounts 
GrayResponseUnit 
GrayResponseCurve 
Group3Options 
Group4Options 
Resolution Unit 
PageNumber 
ColorResponse Unit 
ColorResponseCurves 


Sample TIFF Image Files 


Value/Offset: Offset 
Value: 1 
Value: 1 
Value: 
Value/Offset: 
Value: 0 
Value: 1 
Value: 300 __ 
Value: 300 _ 
Value: 1 
ASCil: 

Value: 

Value: 
Value/Offset: 
Value/Offset: 
Value: 2 
Value/Offset:Offset 
Value: 
Value: 
Value: 
Value: 
Value: 
Value/Offset: 


| 


Note byte order is INTEL format. 


Version #42, Note byte reversal 


Pointer to first directory 
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II. 


Tag 1 
Tag 2 
Tag 3 
Tag 4 
Tag 5 
Tag 6 
Tag 7 
Tag 8 
Tag 9 
Tag 10 
Tag 11 
Tag 12 
Tag 13 
Tag 14 
Tag 15 


Tag 16 
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008 
009 


Directory 


11 
00 


Offset Tag 


O0A 


016 


022 


02E 


03A 


046 


052 


QSE 


06A. 


076 


082 


O8E 


Q9A 


0A6 


OB2 


OBE 


FF 00 


00 O1 


01 01 


02 01 


03 O1 


06 01 


QA 01 


1101 


1201 


15 01 


18 O1 


19 01 


1A 01 


1B 01 


IC 01 


90 02 


' 17 tags in this directory 


Type 
03 00 
03 00 
03 00 
03 00 
03 00 
03 00 
03 00 
04 00 
03 00 
03 00 
03 00 
03 00 
O05 00 
05 00 
03 00 


03 00 


Length 

01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 
01 00 00 00 


01 00 00 00 


Value/Offset 

0100 0000 (Subfile type) 

0A 00 0000 (Image width 10 pixels) 
0A 00 0000 (Image length 10 pixels) 
0400 0000 (4 bits per sample) 

0100 0000 (Packed data compression) 
0000 0000 (Black is 1) 

0100 0000 (Filled MSB to LSB) 

0E 01 0000 (Offset to raster data) 
0100 0000 (Normal orientation) 
0100 0000 (1 sample/pixel) 

0000 0000 (Min value is 0) 

OF 00 0000 (Max value is 15) 

DA 00 0000 (Offset to X resolution) 
E2 00 00 00 (Offset to Y resolution) 
0100 0000 (Planar config is normal) 


0200 0000 (Hundreths) 


Sample TIFF Image Files 


Tagi7 OCA 9102 0300 10000000 EA00 0000 (Pt: gray scale information) 


IIL. 


IV. 


End of directory 


D6 


00000000 (no more directories) 


Extended tag information (as needed) 


DA 
BE? 


EA 
F2 
F6 
FA 
FE 
102 
106 
10A 


2C 010000 01000000 (300 dpi X resolution) 
2C 01 00 00 01000000 (300 dpi Y resolution) 


00 00 09 00 (gray response curve) 
10 00 13 00 

17 00 1B 00 

20 00 24 00 

2B 00 32 00 

39 00 44 00 

4B 00 64 00 

82 00 AQ 00 


Raster data (as needed) 


10E 
113 
118 
11D 
122 
127 
12C 
131 
136 
13B 


66 66 66 66 66 (10 medium gray pixels) 
66 66 66 66 66 (10 medium gray pixels) 
00 00 FF 00 00 (2 black pixels) 
00 00 FF 00 00 (2 black pixels) 
00 00 FF 00 00 (2 black pixels) 
00 00 FF 00 00 (2 black pixels) 
00 00 FF 00 00 (2 black pixels) 
00 00 FF 00 00 (2 black pixels) 
00 00 FF 00 00 (2 black pixels) 
00 00 FF 00 00 (2 black pixels) 


Strip offset pointers (as needed) 
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None needed. 


VI. Strip byte counts (as needed) 


None needed. 


File is 140H bytes long. 
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A Description of the Tags Used for Directory Entries 


4.1 Introduction 


Up until this point, the focus has been on the general structure of a TIFF file. Now, it 
is important to examine each tag that has been defined for the TIFF standard. This 
chapter will discuss each TIFF tag, including information on how each one should be 
used. The description of each tag is intended to supplement rather than replace the 
tag descriptions contained in the official TIFF document. 


The tags are grouped into categories for purposes of discussion. These categories are 
organized as follows: 


Image organization tags 

Image Pointer tags 

Pixel description tags 

Data orientation tags 

Data compression tags 

Document and scanner description tags 
Scanner information tags 

Storage management tags 


Each tag is individually described in this chapter. For each tag, there first appears a 
brief enumeration of the tag values, followed by a detailed description of how the tag 
is used. For example, the ImageWidth tag has the following initial information: 


ImageWidth This is the name of the tag. 


Tag = 256 (100H) This is the value found in the 
first two bytes of the tag. The 
first number is in decimal, and 
the second number is in hexadecimal. 


Type = SHORT This indicates the length of each data 
item associated with this tag. In this 
case, each data item is two bytes in 
length. 


Number of distinct values = 1 


Number of distinct values refers to how 
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many different data items will be 
described by this tag. In this case, 
there is only one value for Image Width 
(which is two bytes long). 


Value range: integers from 0 thru 65535 


This is the range of defined values for 
each data item. In this case, numbers 
from 0 thru 65535 are considered valid 
and must be handled by the TIFF 
application. 


4,2 The Image Organization Tags 


The image organization tags describe the resolution, physical size, orientation, and 
number of image planes. These tags are especially useful when trying to show an ac- 
curate representation of the bitmap image on a screen or on a printed page. Included 
in this Section are: 


SubfileType 
ImageLength 

Image Width 
XResolution 
YResolution 
Resolution Unit 
Orientation 
PlanarConfiguration 


4.2.1 The SubfileType Tag 


SubfileType 

Tag = 255 (FFH) 

Type = SHORT 

Number of distinct values = 1 
Value range = 1,2, or3 
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This tag is used as an overall description of the bitmap data pointed to by the direc- 
tory. There is one of these tags recommended for each bitmap image in the TIFF file. 
Most TIFF files include only 1 bitmap image, and so only one of these tag values will 
appear in the corresponding TIFF directory. If this valuc is not present in the TIFF 
header, readers will assume that the bitmap is present and it is a full resolution image. 


This tag was designed for applications that want to include 2 or more bitmaps in a 
single TIFF file. 


There are three values that this tag can take: 1, 2, or 3. A value of "1" indicates that the 
image is of full resolution. A value of "2" indicates that the image pointed at by this 
directory is of reduced resolution, and is a reduced version of a corresponding full 
resolution image. (By having both images, it is possible to speed up the time to show 
the reduced resolution image on the screen since it doesn’t have to be created from 
the full-resolution image.) Thus, if there is a SubfileType tag of type 2, there must be 
a corresponding directory that contains a SubfileType tag of type 1. A value of "3" rep- 
resents a single page of a multi-page image. For a multi-page image, the PageNumber 
tag is used to specify the page number attached to the associated bitmap. 


Note that if this tag is present (which is not a requirement in the official TIFF stand- 
ard), three other tags are required. These are the ImageWidth, ImageLength, and 
StripOffsets (pointer to image data) tags. Be sure these are present. In fact, it is highly 
recommended that a minimum TIFF file include at least the SubfileType, Image- 
Width, ImageLength, and StripOffset tags. If a resolution is known for the image, this 
should be included as well. 


4.2.2 The ImageWidth Tag 


Image Width 

Tag = 256 (100H) 

Type = SHORT 

Number of distinct values = 1 

Value range: integers from 0 through 65535. 


ImageWidth describes the width of the image in pixels. The width is assumed to be in 
the X direction (horizontal axis). Another way to think of it is the number of columns 
in the image. 


This tag is really a required tag, since readers of TIFF files can’t do much with the 
image without knowing how many pixels are used in the X direction. 
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Readers of TIFF files should be sure that the value for image width is not larger than 
can be handled with their memory management strategies. Reading applications 
should at least be able to handle a full-width 8.5" image at 300 dpi (2550 pixels). Most 
writing applications provide this kind of output. 


4.2.3 The ImageLength Tag 


ImageLength 

Tag = 257 (101H) 

Type = SHORT 

Number of distinct values = 1 

Value range: integers from 0 through 65535. 


Image length describes the length of the image in pixels. The length is assumed to be 
in the Y direction (vertical axis). Another way to think of it is the number of rows in 
the image. 


As in the case of image width, if the image is not a rectangle, then ImageLength must 
be set to the longest column (greatest number of rows) of the image. The image must 
be stored as the maximum required rectangle. 


This tag is really required since readers of TIFF files can’t do much with the image 
without knowing how many pixels are used in the Y direction, as well as in the X direc- 
tion. 


Again, readers of TIFF files should be sure that the value is not larger than can be ap- 
propriately handled. Readers should at least be able to handle a maximum 14" image 
at 300 dpi (4200 pixels). There already exist TIFF writers that will produce this many 
rows of pixels. 


4.2.4 The XResolution Tag 


XResolution 

Tag = 282 (11AH) 

Type = RATIONAL 

Number of distinct values = 1 

Value range: from 1/((2**32)-1) thru (2**32)-1 
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The X resolution expresses the number of pixels per ResolutionUnit in the X direc- 
tion (horizontal axis). 


This information is pertinent to both screen painting programs and scanner applica- 
tions. It is especially important for scanners which can allow scanning at different 
resolutions (usually by taking a fixed resolution image and either dropping or duplicat- 
ing selected pixels). Other input devices, such as cameras, won’t need to make use of 
this tag. 


Resolution is really a key piece of information in desktop publishing. Most users really 
expect the image that is displayed on the screen to be the same size as was prepared 
by the image input program. The resolution information helps properly transform the 
data so that it can be shown with the same height and width as it was intended to be. 
This becomes especially critical when working with dithered images which don’t 
tolerate scaling. (Dithered images lose their structural pattern of 1’s and 0’s when 
scaled and no longer accurately represent the shades of gray as originally intended.) 


There are a number of choices for numerator and denominator that can be used to ex- 
press resolution. Most should work fine, although the most reduced fractional number 
is probably what is expected and has probably been tested. For example, to express 
150 dpi, use 150/1 rather than 300/2. To express 73.5 dpi one must use 147/2 since in- 
teger numbers must be used. The reading application will need to do the proper con- 
versions into the coordinate system and unit systems that apply. 


Readers and writers supporting scanners currently use values from around 75 dpi to 
300 dpi. This range is expected to grow over the near term. It is safe to assume that 
most writers and readers will cover 75, 150, and 300 dpi effectively. Other values 
should be carefully checked to be sure that compatibility can be achieved. | 


4.2.5 The YResolution Tag 


YResolution 

Tag = 283 (11BH) 

Type = RATIONAL 

Number of distinct values = 1 

Value range: from 1/((2**32)-1) thru (2**32)-1 


The Y resolution expresses the number of pixels per resolution unit in the Y direction 
(vertical axis). Please refer to the discussion under the X resolution tag for more infor- 
mation. 
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4.2.6 The ResolutionUnit Tag 


ResolutionUnit 

Tag = 296 (128H) 
Type = SHORT 
Value range: 1, 2, or 3 


The resolution unit specifies the unit used by the XResolution and YResolution 
fields. The default is inches (value = 2). Most desktop publishing applications as- 
sume inches as their standard unit. Many existing TIFF readers and writers don’t 
make use of this tag. If deviating from the inches default, it is recommended that you 
carefully do interchange testing with the receiving application. Readers of TIFF files 
should assume if this tag is not present that the default of inches is used. 


1: No unit of resolution. The resolution numbers are interpreted to determine an 
aspect ratio. 

2: inch 

3: centimeter 


4.2.7 The Orientation Tag 


Orientation 

Tag = 274 (112H) 

Type = SHORT 

Number of distinct values = 1 
Value range: 1 through 8 


The orientation tag describes the orientation of the bitmap by specifying the origin for 
both the X and Y directions. There are 8 possible orientations of an image. Each 
corner can be the reference point, and the image be either inverted or not inverted. 


The eight values are as follows: 
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1: The first row of the bitmap is the visual top of the image, and the first column of the 
bitmap is the visual left hand size of the image 


2: Ist row = top of image, 1st column = right hand side 

3: Ist row = bottom of image, Ist column = right hand side 
4: 1st row = bottom of image, 1st column = left hand side 
5: Ist row = left hand side, 1st column = top of image 

6: Ist row = right hand side, Ist column = top of image 

7: Ist row = right hand side, 1st column = bottom of image 
8: Ist row = left hand side, 1st column = bottom of image 


The first value is the default and is the one that should be used when writing a TIFF 
file. Very few readers of TIFF files support other than the default entry for orienta- 
tion. (A few will have greater flexibility and will permit all 8, however.) It is recom- 
mended that writers of TIFF files use this default value as well. 


Changing the value of this tag effectively rotates an image by changing the reference 
point. However, although it does quick rotation when writing out the information, the 
TIFF reader must still take the time to transform the pixel information into the new 
orientation. 


4.2.8 The PlanarConfiguration Tag 


PlanarConfiguration 

Tag = 284 (11CH) 

Type = SHORT 

Number of distinct values = 1 
Value range: 1, 2 


This tag describes how data is organized when working with color and gray scale infor- 
mation. It is not really intended for black and white data. In fact, it isn’t really neces- 
sary when working with gray scale information. 


Bitmaps that represent color or gray-scale data can be organized in one of two ways. 
Either all the information about each pixel can be stored contiguously, or each plane 
of color can be stored contiguously. For example, in figure 4.1, there is a bitmap image 
that is 2 pixels wide by 2 pixels long. There are 3 different color specifications for each 
pixel in this example (red, green, and blue). If the planar configuration is set to 1, then 
the data is stored as shown in part A of the figure. As shown, all four color specifica- 
tions are stored contiguously for each pixel. If the planar configuration is set to 2, then 
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4 PIXELS 
2X2 


ALL VALUES SHOWN 
IN HEX 


CONFIG 1: A3, B2, 04, A4, B2, 09 (ROW 1) 
AS, B3, 03, A6, B1, 04 (ROW 2) 


COMFIG 2: 
A3, A4 (ROW 1) 


As, AB (ROW 2) 
B2, B2 (ROW) 
B3, B1 (ROW 2) 
04,09 (ROW 1) 
03,04 (ROW 2) 


Figure 4.1 


each color plane is stored contiguously. In other words, all of the red specifications 
are kept together, followed by the green, blue, and black specifications. 


Note that the photometric interpretation information must be taken into account 


when interpreting this tag. The default value is 1. 


The choice of which value to support is dependent upon the data architecture used in 
the application. If the color or gray information is already organized as separate 


48 


RED 
RED 
GREEN 
GREEN 
BLUE 
BLUE 


A Description of the Tags Used for Directory Entries 


planes, then the planar configuration might be more useful, and vice-versa. TIFF 
reader applications are recommended to handle both possible configurations. 


Please see the examples in Chapter 3 for more information. 


4.3 A Description of the Image Pointer Tags 


This section describes the tags that are used to point at actual bitmap data. Bitmap 
data can either be pointed to by a single offset, or many offsets may be available that 
can provide quick access to different portions of compressed bitmap data. 


The following tags are included in this discussion: 


StripOffsets 
StripByteCounts 
RowsPerStrip 
StripsPerImage 


Before presenting each individual tag, it is helpful to first look at the overall structure 
of pointers for a TIFF file. Figure 4.2 shows a sample bitmap image and superimposes 
on the bitmap the pointer structure used in TIFF. Note that the bitmap has been 
divided up into several partitions, known as strips. Each strip is pointed to by a 
pointer in the header of the TIFF file. Thus, if an application program needs quick ac- 
cess to a portion of the image, then the nearest pointer can be used. 


This structure becomes useful when data compression is being used. Many data com- 
pression techniques require that the compressed data be decoded sequentially, start- 
ing at the first byte of the data. This is because to decompress the next byte in the file, 
information from the previous byte must be used. To access and decompress bytes 
from the middle of a bitmap image requires the entire bitmap to be read sequentially. 
Without special pointers, decompression of the middle portion requires first 
decompressing the initial portion of the image, regardless of whether the 
decompressed information from the initial portion is needed. This can be time con- 
suming. However, if data compression starts anew with a strip of the image, then the 
application need only go to the nearest strip and start doing the decompression. 


This data structure illustrates the classic tradeoff between storage space and algo- 
rithm speed when used with compressed data. As more and more pointers are used, 
access to any given bitmap row becomes quicker, but the header of the TIFF file will 
get proportionately larger. The worst case is one pointer per row of bitmap data. This 
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OFFSET 1 ad 
OFFSET 1 ad 
OFFSET 1 ad 


STRIP 4 se 


STRIP 2 


N ROWS/STRIP 


STRIP 2 


BIT-MAP IMAGE 
DIVIDED INTO 3 
STRIPS 


Figure 4.2 


provides the quickest access time at the expense of storage overhead. For example, in 
TIFF each pointer requires 4 bytes. For a 4" x 5" image at 300 dpi, there are 1500 rows 
which would result in 6000 additional bytes of overhead. Since the total image re- 
quires about 75K bytes (225K uncompressed bytes and assuming a 3:1 compression 
ratio), this represents about 8% of the total file space. 


The least overhead and the slowest access time would be achieved by having one 


pointer to the entire bitmap. This would require 4 bytes of overhead (an overhead of 
about .005%). 
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In summary, if a pointer is available to the desired information, then unnecessary data 
decompression time can be avoided. 


More information on the use of this data structure appears in Chapter 5 of this docu- 
ment. 


43.1 The StripOffsets Tag 


StripOffsets 

Tag = 273 (117H) 

Type = SHORT OR LONG 
Number of distinct values one per strip for single plane bitmaps 


number of planes x strips/plane for multi-plane bitmaps 


0 to (2**32)-1 for LONG 
= 0 to (2**16)-1 for SHORT 


Value range: 


The StripOffsets tag will either be a single pointer to the start of the bitmap (figure 
4.3a), or it will be a single pointer that points to an array of pointers (figure 4.3b). In 
this second case, each pointer in the array will point to the next strip of the bitmap. 


Bea ed MM 


BIT - MAP 


DATA 


I 


Figure 43a 
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Note that the pointer values are really offsets with respect to the beginning of the 


TIFF file. 
on 


STRIP POINTER 14 
STRIP POINTER 2 


ie ee ee 


STRIP POINTER 49 


Figure 4.3b 


Note: At least one StripOffset value is required in a TIFF file if the writer wants the 
reader to find the bitmap data! 


If an application that writes a TIFF file wants to provide the best speed performance, 
then it is recommended that every row or every other row have a strip offset pointer. 
This will provide a performance improvement for TIFF readers that either need to 
decompress portions of an image, or need to read subsets of the image. For example, 
often a TIFF reader will want to take a high resolution image (for example, 300 dpi) 
decompress it, and display a reduced resolution version to the screen (for example, at 
75 dpi). Only every fourth row of the bitmap would need to be accessed in this case. A 
strip offset for every row prevents having to decompress all 4 rows when only 1 row is 
really needed. 


Readers are encouraged to 1) always be able to make use of the first strip offset 


(which may be at the head of an array of pointers), and 2) to take advantage of multi- 
ple strip offsets if data compression is supported. 
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Note that the type for this tag can be either SHORT or LONG. LONG is the default 
and is used by virtually all TIFF reading and writing applications. SHORT values may 
be used for very short TIFF files. However, its use is discouraged since most existing 
TIFF software doesn’t check the TYPE field of a tag. 


4.3.2 The StripByteCounts Tag 


StripByteCounts 

Tag = 279 (117H) 

Type = LONG 

Number of distinct values one per strip for single plane bitmaps 

number of planes x strips/plane for multi-plane 


bitmaps 


Value range: 0 to (2**32)-1 


Each StripOffset value has associated with it a StripByteCount value (see figure 4.4). 
This information is used to verify that the correct number of bytes are read when 
doing decompression. 


The StripByteCounts tag is currently only defined for CCITT/3 compression. In the fu- 
ture, it may apply to other compression techniques. 


The value for each StripByteCount is determined during data compression. After all 
the rows in each each strip have been compressed, the total number of compressed 
bytes is totaled and becomes the value used for StripByteCount. 


Again, note that if the image has more than one strip offset, there will be more than 
one value for StripByteCount. 


Note that the StripByteCounts tag may not be present if there is only one strip offset 
and no data compression. This field is necessary if the data is compressed. 
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43.3 The RowsPerStrip Tag 


RowsPerStrip 

Tag = 278 (116H) 

Type = SHORT or LONG 

Number of distinct values = 1 

Value range: 0 to (2**32)-1 for LONG 
0 to (2**16)-1 for SHORT 


RowsPerStrip indicates the number of uncompressed rows that are represented in 
each strip. Note that this requires that all strips (except for the last one) represent the 
same number of uncompressed rows. If there is only one StripOffset in the entire 
image, then rows per strip is set at it’s maximum value of (2**32)-1 or (2**16)-1 ac- 
cording to data type. 


In the case where there is only one strip-offset in the entire image, it is also valid for 
the application writing the TIFF file to write the actual number of rows in the entire 
bitmap. Either is correct, and the reading application should be able to handle both 
cases. 


Note that this tag is valid if data compression is not being used. However, a TIFF 


reader application can easily recreate the the number of rows per strip since the 
length of each uncompressed row is a constant. 
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Note that the last strip of an image can contain RowsPerStrip uncompressed rows or 
less. (See figure 4.5). This still permits the TIFF reader software to adequately locate 
the desired strip containing the desired data. 


OFFSET 1 ——+ FULL 


STRIP 0 


OFFSET 2 ——+ FULL 


STRIP @ 


OFFSET3 ———> STRIP 2 REMAINDER 


Figure 4.5 


The default value for RowsPerStrip is (2**32)-1. It is recommended that the writer 
write out the actual number of rows in the image. TIFF reading applications should be 
able to handle either the default value, no value, or the actual number of rows in the 
image. 


It is recommended that TIFF readers read this tag and handle either the maximum 
possible value, or any other value appropriately. 


Short or long types can be used for this field. The default is long. All existing TIFF 
reading and writing software makes use of long as the type. Short types are to be 
avoided if possible. 


4.3.4 The StripsPerImage Tag 


Note that this value is not a tag, and it will not appear in a TIFF header. Although the 
presence of this tag in the document is a little confusing, it can be useful to calculate 
this value when developing and implementing TIFF code. The number of strips in an 
image is 1 if there is only one strip defined, or it is the number of total rows in the 
image divided by the number of rows per strip. If a fractional number results, then the 
number is the next largest integer number. 
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This field is especially useful when finding out how many times strip offset poimters 
must be retrieved. 


4.4 The Pixel Description Tags 


These tags describe whether the bitmap data is binary, gray-scale, or color. Further, 
they give information about how to interpret the meaning of the bitmap. Knowing this 
information, the bitmap data can be converted to the appropriate colors or combina- 
tions of dots on the target output device. 


These tags need to be checked carefully by a TIFF reader to insure that a particular 
image can be properly handled. For example, if the file is in color, and only 
black/white is supported, then an appropriate file rejection message will need to be 
given to an end user. 


TIFF writers will need to coordinate very carefully with TIFF readers when support- 
ing gray scale and color. These features are relatively new and not much work has 
gone into compatibility checking. 


The tags in this section include: 


SamplesPerPixel 
BitsPerSample 
Thresholding 
CellWidth 

CellLength 
MinSample Value 
MaxSampleValue 
PhotometriclInterpretation 
GrayResponseCurve 
GrayResponseUnit 
ColorResponseCurves 
ColorResponse Unit 


Most of these tags start to come into play when color or gray scale are being used. For 
black and white or dithered images, only a few of these tags are really necessary. 
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4.4.1 The SamplesPerPixel Tag 


SamplesPerPixel 

Tag = 277 (115H) 

Type = SHORT 

Number of distinct values = 1 
Value range: 1 through 65535 


This tag represents the number of samples per pixel. For black and white data, the 
value will be 1. For 3 plane color data, the value will be 3. For 4 or 6 bit gray scale, the 
value will usually be 1 since gray scale does not require separate planes in a TIFF file. 
However, it is possible to store the gray scale information in separate planes for case 
of data compression. In this case, each plane holds one bit of the gray scale pixel 
value. 


Readers should check this tag carefully to be sure that the information can be hand- 
led. Writers must also carefully specify this tag. Note that the default value is 1 for 
black/white, gray scale, and dithered data. 


Currently, 1 and 3 are the only values that are in use by most TIFF readers and 
writers. If other values are needed, it is advisable to coordinate closely with the TIFF 
reader/writer application as appropriate. 


4.4.2 The BitsPerSample Tag 


BitsPerSample 

Tag = 258 (102H) 

Type = SHORT 

Number of distinct values = SamplesPerPixel 
Value range: 1 through 65535 


The BitsPerSample tag is used to describe how many bits are required to represent 
each sample associated with a pixel. For black and white images, 1 bit is all that is re- 
quired for each sample, and there will be only 1 sample per pixel. Thus, each pixel will 
require only 1 bit. For 4 bit gray scale, each sample will require 4 bits. Since gray scale 
has 1 sample per pixel, then each pixel will require 4 bits. Finally, for 3 plane color in- 
formation with 8 bits of information per color, each sample will require 8 bits. Since 3 
plane color requires 3 samples per pixel, then 24 bits will be needed per pixel. (See 
figure 4.6.) 
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This tag allows a different number of bits per sample for each sample corresponding 
to a pixel. For example, for RGB color data there could be 8 bits per red pixel, 6 bits 
per green pixel, and 4 bits per blue pixel. Note that RGB samples per pixel are stored 
in the order R, G, and B. In this example, BitsPerSample would be stored as 8,6,4. 
Even if all samples are the same size, a sample size must be stored for each sample- 
per-pixel. 


TIFF readers should check this tag to be sure that the information can be interpreted. 
For example, if gray scale is supported, it is important to see if the number of bits per 
pixel can be handled. If color is supported, it is important to be sure that both the 
number of planes and the appropriate sample data can be properly needed. 


Gray scale and color are currently being implemented. Four and six bits are common 
for gray scale. Eight and twelve bits are common for color. These would be important 
values to use for design purposes. Again, close coordination between readers and 
writers is recommended when using these features. 


4.4.3. The Thresholding Tag 


Thresholding 

Tag = 263 (107H) 

Type = SHORT 

Number of distinct values = 1 
Value range: 1 through 3 


Threshholding is an information tag that tells how the bitmap image was formed. 
When present, it indicates that some image processing has been done on an original 
image, and a representation is present in the bitmap image. For example, some input 
devices can detect shades of gray from an image. These shades of gray (gray scale) 
were then converted to a black and white image, or they were converted to ap- 
propriate patterns of black and white dots to simulate shades of gray when viewed on 
an output device (dither matrix or error diffusion techniques). 


There are three currently defined values for this tag. 


1: A bi-level "line art" image. Bits per sample must be 1 
in this case. 
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2: A dithered image, formed by converting gray information into an appropriate com- 
bination of black and white dots. Bits per sample must be 1 in this case. 


3: An error diffused image, formed by converting gray information into an ap- 
propriate combination of black and white dots or gray dots using error diffusion tech- 
niques. 


It is recommended that TIFF writers specify this value since it 1s very useful for TIFF 
readers. For example, TIFF readers can check this value to avoid scaling a dithered or 
an error-diffused image. (Scaling will disturb the pattern of black and white dots and 
create image distortion.) 


4.4.4 The CellWidth and CellLength Tags 


CellWidth 

Tag = 264 (108H) 

Type = SHORT 

Number of distinct values = 1 
Value range: 1 through 65535 


CellLength 

Tag = 265 (109H) 

Type = SHORT 

Number of distinct values = 1 
Value range: 1 through 65535 


The CellWidth and CellLength tags indicate the dimension of a dithering matrix. 
These values only apply if a dithering technique is being used. Thus, the Thresholding 
tag needs to be present in the directory and set to a value of 2. 


These are information-only tags, and may be useful if the reading application wants to 
try image processing of dithered data. Since it is not guaranteed that synchronization 
of the dithering pattern can be made with the received dithered data, synchronization 
must be done by using some intelligent heuristics in the TIFF reading software (i.e., 
lining up the dither matrix with the data in the bitmap). Also, the reading application 
must know what dither matrix values were used by the writing application. 


Very few, if any, applications are using these tags because of the aforementioned con- 


straints. In the near future, it is predicted that most applications will do image process- 
ing using gray-scale information prior to conversion to dither patterns. 
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Note that most dither matrices are 4x4, 4x6, or 8x8 in size. 


If you want to make use of this information, it is recommended that you verify which 
dither pattern is in use and whether or not it is easy to synchronize on the dither 
matrix in use. 


4.4.5 The MinSampleValue and MaxSampleValue Tags 


MinSample Value 

Tag = 280 (118H) 

Type = SHORT 

Number of distinct values = 1 
Value range: 0 through 65535 


MaxSampleValue 

Tag = 281 (119H) 

Type = SHORT 

Number of distinct values = 1 
Value range: 0 through 65535 


The minimum and maximum sample values tags are used to know how to "interpret" 
or translate the bitmap image into the appropriate color levels on an output device. 
These tags are used with the PhotometricInterpretation tag described below to ac- 
complish this task. 


The minimum sample value describes the smallest value expected per sample. The 
maximum value describes the largest value expected per sample. The default mini- 
mum sample value default is 0, and the default maximum sample value is (2**BitsPer- 
Sample)-1. 


For example, in a black and white image the minimum sample value is 0, and the maxi- 
mum sample value is 1. For a 4-bit gray scale image, the minimum sample value is 0 
and the maximum sample value is 15. 


Writers of TIFF files should specify these tags, especially if the default values aren’t 
being used. Readers of TIFF files should check these tags to be sure that 1) the value 
range can be supported, and 2) to see if any special image processing needs to be 

done, For example, if 4 bit gray scale is supported but the sample value range goes 
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from 2 through 8, then perhaps some additional image processing needs to be done on 
the data to expand it to the full 16 levels possible. 


4.4.6 The PhotometricInterpretation Tag 


PhotometricInterpretation 
Tag = 262 (106H) 

Type = SHORT 

Number of distinct values = 1 
Value range = 0 through 2 


This tag describes how to interpret the actual values in the bitmap when sending the 
information to an output device. There are 4 currently defined models for this tag. 


Q: The minimum sample value specified should be output as white. The maximum 
sample value specified should be output as black. If the bitmap represents gray scale, 
then the values between the minimum and maximum sample values should be inter- 
preted according to either the gray scale response curve information (if included) or 
according to the result of an image processing algorithm. 


1: The minimum sample value specified should be output as black. The maximum 
sample value specified should be output as white. If the bitmap represents gray scale, 
then the values between the minimum and maximum sample values should be output 
according to either the gray scale response curve information (if included) or accord- 
ing to the result of an image processing algorithm. 


2: RGB photometric interpretation. The minimum sample value represents minimum 
intensity and the maximum sample value represents maximum intensity. In the RGB 
color model, the three primary colors of light (red, green, and blue) are specified in 
different concentrations. 


Note that the red, green, and blue values are defined according to the NTSC specifica- 
tions that govern the interpretation of these colors. 


Most TIFF writers currently use 0 as the default, but some will use 1 and will require 
that the receiving application do a conversion on the data before writing the informa- 
tion to a laser printer. It is recommended that TIFF writers specify clearly which inter- 
pretation is being used. 


Writers should choose a value that requires the least processing. 
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It is recommended that TIFF readers support both 0 and J as possible values. Never 
assume that the value will be a 0 (or a 1). 


Note: If binary images are used with CCITT/3 compression, this field does not apply. 
CCITT/3 defines the photometric interpretation for binary data. 


4.4.7 GrayResponseCurve and GrayResponseUnit 


GrayResponseCurve 

Tag = 291 (123H) 

Type = SHORT 

Number of distinct values = 2**BitsPerSample 
Value range = 0 through 65535 


GrayResponse Unit 

Tag = 290 (122H) 

Type = SHORT 

Number of distinct values = 1 
Value range = 1 through 5 


1: number represents tenths of a unit. 

2: number represents hundreths of a unit. 

3: number represents thousandths of a unit. 

4: number represents ten-thousandths of a unit. 

5: number represents hundred-thousandths of a unit. 


The purpose of the gray response curve and the gray response unit is to further 
provide photometric interpretation information for gray scale image data. The gray 
response curve specifies for given levels of gray between the minimum and maximum 
sample values the actual photometric gray level of the value. It represents this gray 
level in terms of optical density. 


The gray scale curve can act as a "lookup" table mapping values from 0 through 
2**BitsPerSample-1 into specific density values. 


The GrayResponseUnit specifies the accuracy of the information contained in the 


curve. Since optical density makes use of fractional numbers, then this tag is necessary 


to know how to interpret the stored integer information. For example, if Gray- 
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Response Unit is set to 3 (thousandths of a unit), and a GrayResponseCurve number 
for gray level 4 is 345, then the resulting actual value is 0.345. The default is 2. 


If the gray scale response curve is known for the data in the TIFF file, and if the gray 
scale response of the output device is known, then an intelligent conversion can be 
made between the input data and the output device. For example, the output can be 
made to look just like the input. In addition, if the input image lacks contrast (as can 
be seen from the response curve), then appropriate contrast enhancements can be 
made. 


4.4.8 ColorResponseCurves and ColorResponseUnit 


ColorResponseCurves 

Tag = 301 (12DH) 

Type = SHORT 

Number of distinct values = 2**BitsPerSample (red) + 
2**BitsPerSample (green) + 
2**BitsPerSample (blue) 

Value range = 0 through 65535 


ColorResponseUnit 

Tag = 300 (12CH) 

Type = SHORT 

Number of distinct values = 1 
Value range = 1 through 5 


1: number represents tenths of a unit 

2: number represents hundreths of a unit 

3: number represents thousandths of a unit 

4: number represents ten-thousandths of a unit 

5: number represents hundred-thousandths of a unit 


The purpose of the color response curves and the color response units is to further 
provide photometric interpretation information for color image data. These curves 
work in the same manner as does the gray scale response curve, but there are three 
curves rather than one. The color response curves specify for given levels of color be- 
tween the minimum and maximum sample values the actual photometric color level of 
the value. It represents this color level in terms of optical density. 
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The color curves can act as a "lookup" table mapping values from 0 through 2**Bits- 
PerSample-1 into specific density values. 


The curve values are stored sequentially in red-green-blue order. The size of each 
table is 2**BitsPerSample, using the BitsPerSample value corresponding to the 
respective color. 


The ColorResponseUnit specifies the accuracy of the information contained in the 
curve. Since optical density makes use of fractional numbers, then this tag is necessary 
to know how to interpret the stored integer information. For example, if Color- 
Response Unit is set to 3 (thousandths of a unit), and a color curve value for red level 
4 is 556, then the resulting actual value is 0.556. The default 1s 2. 


Similar image processing functions can be performed on the color data as can be 
done on gray scale data. 


4.5 The Data Orientation Tags 


The data orientation tags specify how the data is actually stored in the bitmap image. 
This data is critical to specify since there are several possible ways to orient the pixel 
information in the bitmap. The only tag currently defined under TIFF is the Fillorder 
tag. 


4.5.1 The FillOrder Tag 


FillOrder 

Tag = 266 (10AH) 

Type = SHORT 

Number of distinct values = 1 
Value range: 1 through 2 


The fillorder tag specifies how the data values for each pixel are organized into bytes. 
The values are: 


1: As each pixel is placed into a byte according to the fill order, they are placed into a 
byte from left to right (from most significant to least significant position) 
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2: As each pixel is placed into a byte according to the fill order, they are placed into a 
byte from right to left (from the least significant to the most significant position) 


The default value is 1. Writers and readers are both encouraged to support this 
default. A reader that wants to have the greatest flexibility is encouraged to support 
both fill orders. However, very few (if any) applications that write TIFF files will use 
the second filling order. 


4.6 The Data Compression Tags 


Data compression is a key feature that is needed when working with bitmap images. 
One of the important benefits of TIFF is easy expansion for many different kinds of 
data compression. Currently, there are several compression schemes defined for black 
and white images, and a number of private schemes are being developed and used. 


4.6.1 The Compression Tag 


Compression 

Tag = 259 (103H) 

Type = SHORT 

Number of distinct values = 1 
Value range = 1 through 2 


Data compression only applies to the actual bitmap image data pointed to by a strip 
offset. Thus, the header and the other portions of a TIFF file are not compressed. The 
values used are: 


1: No compression is used. However, the pixel information is packed into bytes ac- 
cording to fill order and planar configuration as tightly as possible. Each row of bit- 
map information is padded with arbitrary data to fill out to a byte boundary. 


If the number of bits per sample is greater than 8, TIFF stores the data into 16 and 32 
bit quantities. This allows better efficiencies when working with larger quantities of in- 
formation (data can be fetched in larger units). If bits per sample is greater than 8 and 
less than or equal to 16, then the data is stored in two byte units. If bits per sample is 
greater than 16 but less than or equal to 32, then the data is stored in four byte units. 
The Intel and Motorola byte orders apply for 16 and 32 bit data as appropriate. 
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TIFF data not using compression doesn’t always need to be packed. To specify that 
the data is not packed, the BitsPerSample, MinSampleValue, and MaxSample Value 
tags can be adjusted appropriately. This is accomplished in TIFF by specifying the 
next higher power of 2 in the BitsPerSample field. For example, to represent 6 bit 
data having 63 different distinct values in unpacked form, the following tag values 
would be used: 


BitsPerSample: 8 (even though only 6 bits are used) 
MinSampleValue: 0 
MaxSampleValue: 64 (6 bits of resolution) 


This convention requires that TIFF readers check the MinSampleValue and Max- 
SampleValue fields to be sure that the appropriate ranges are used. TIFF readers 
must also check these values when deciding whether or not the data is stored im pack- 
ed form. 


2: Modified CCITT/3 1-D compression. This compression scheme is similar to 
CCITT/3 1-D with the exception that no terminating characters are used and each 
new row in the bitmap is compressed independently of a previous row. More informa- 
tion on this is shown in later chapters of this document. 


Note that when CCITT/3 data compression is being used, the strip offsets and other 
pointers will probably be used to speed performance. 


The following two schemes are available for FAX communication. They are not 
recommended in the context of desktop publishing except when communicating with 
FAX machines or when communicating with computers operating in FAX mode. In 
fact, most TIFF reading applications don’t support these options. Details on these 
coding schemes can be found in the official TIFF document and in the official CCITT 
documentation published in 1985 covering facsimile transmission standards: 


3: Facsimile-compatible CCITT Group 3. Each strip begins on a byte boundary. The 
data is stored as bytes, not as words. Terminating characters are used in this scheme 
so that FAX communication is possible. Rows that are not the first row of a strip are 
not required to begin on a byte boundary since terminating characters are used. 


4: Facsimile-compatible CCITT Group 4. Each strip must begin on a byte boundary. 


Rows that are not the first row of a strip are not required to begin on a byte boundary 
since terminating characters are used. 
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Several private schemes are in existence, which are indicated by private values that 
are 32768 through 65535. If a reader encounters this value and doesn’t understand 
the compression scheme, then the TIFF file needs to be rejected. 


Two of these private schemes have now been made public. To insure backwards TIFF 
compatability, these schemes retain their private values: 


32771: Same compression as compression type 1, except that each row begins on the 
next available word boundary, instead of the byte boundary. This scheme is not recom- 
mended for compatability for most DTP applications. 


32773: PackBits compression, as detailed in the appendix of the official TIFF docu- 
ment. 


Writers and readers who use private compression schemes need to coordinate closely 
to insure compatibility. 


4.6.2 Group3Options 


Group3Options. 

Tag = 292 (124H) 

Type = LONG 

Number of distinct values = 1 


Group3Options is a set of 32 flag bits. All unused bits are set to 0. Bit 0 is the low- 
order bit. This set of flag bits is set to 0 for the default case. Most readers and writers 
of TIFF files will not use this tag, or will use the default value of this tag. This conven- 
tion should be followed if the widest possible interchange of TIFF files is desired. The 
default is zero. 


Bit 0: Set to 0 for standard 1-dimensional encoding. 
Set to 1 if 2 dimensional encoding is followed. For 2-D coding, if more than one strip 
is specified, each strip must begin with a 1-dimensionally coded line. In other words, 


RowsPerStrip should be a multiple of "parameter K" as documented in the CCITT 
specification governing 2 dimensional encoding. 
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Bit 1: Set to 1 if uncompressed mode is being used. 


Bit 2: Set to 1 if fill bits have been added as necessary before EOL (End Of Line) 
codes such that EOL always ends on a byte boundary, thus ensuring an EOL-se- 
quence of 1 byte preceded by a zero nibble: xxxx-0000 0000-0001. 


4.6.3 Group4Options 


Group4Options 

Tag = 293 (125H) 

Type = LONG 

Number of distinct values = 1 


- Group4Options is a set of 32 flag bits. All unused bits are set to 0. Bit 0 is the low- 
order bit. This set of flag bits is set to 0 for the default case. Most readers and writers 
of TIFF files will not use this tag, or will use the default value of this tag. This conven- 
tion should be followed if the widest possible interchange of TIFF files is desired. The 
default is 0. 


For 2-D coding, each strip is encoded as if it were a separate image. See the TIFF 
document and additional CCITT/4 documentation for further explanation. 


Bit 0: Unused. 


Bit 1: Set to 1 if uncompressed mode is being used. 
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4.7 The Document and Scanner Description Tags 


The document and scanner description tags are fairly straightforward. They are in- 
tended for informational purposes only. Very few writers or readers of TIFF files are 
making use of this information, but under some conditions they can be useful. An ap- 
plication should be careful about depending on these tags since they are informational 
only. If these tags are necessary for your application, it is recommended that close 
coordination be done with all intended readers/writers of the TIFF file. 


There are 7 values defined for the description tags: 


DocumentName 
PageName 
XPosition 
YPosition 
ImageDescription 
Make 

Model 
PageNumber 


The descriptions are self-explanatory and are repeated here only for completeness. 


4.7.1 The DocumentName Tag 


DocumentName 

Tag = 269 (10DH) 

Type = ASCII 

The name of the document from which this image was scanned. No default. 


4.7.2 The PageName Tag 


PageName 
Tag = 285 (11DH) 
Type = ASCII 
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The name of the page from which this image was scanned. 


4.7.3 The XPosition and YPosition Tags 


XPosition 

Tag = 286 (11EH) 

Type = RATIONAL 
Number of distinct values = 1 
Value range: Rational 


YPosition 

Tag = 287 (11FH) 

Type = RATIONAL 
Number of distinct values = 1 
Value range: Rational 


These describe the X and Y offsets of the left and top of the image, respectively. They 
indicate the location of the scanned image with respect to the original document. The 
origin is at the upper-left corner of the original document, and both positions are 
measured in inches. In the TIFF coordinate scheme, the positive Y direction is down, 
so that the YPosition tag value will always be positive. 


4.7.4 The Image Description Tag 


ImageDescription 
Tag = 270 (10EH) 
Type = ASCII 


The image description tag is used to store any miscellaneous ASCII information that 
applies to the current image. There is no default. 


4.7.5 The Make and Model Tags. 


Make 
Tag = 271 (10FH) 
Type = ASCII 
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The name of the scanner manufacturer. No default. 


Model 
Tag = 272 (110H) 
Type = ASCII 


The model name and number of the scanner. No default. 


4.7.6 The PageNumber Tag 


PageNumber 

Tag = 297 (129H) 

Type = SHORT 

Number of distinct values = 2 


The PageNumber tag is used to specify page numbers for a multiple page document 
(especially a FAX document). Two short values are specified. The first value is the 
page number, and the second value is the total number of pages in the document. It 
isn’t required for the pages to be in numerical order. Thus, the TIFF reading applica- 
tion should refer to this tag to determine the proper page order. 


4.8 The Storage Management Tags 


The storage management tags are useful if TIFF 1s being used as a working file format 
in addition to being used as an interchange file format (in other words, one applica- 
tion both writes and reads TIFF files, and may do so many times while processing and 
displaying a given image). The storage management tags are used to indicate available 
space in a TIFF file that can be reclaimed for other purposes. 


There are two tags in this category, FreeOffsets and FreeByteCounts. 


4.8.1 The FreeOffsets Tag 


FreeOffsets 

Tag = 288 (120H) 

Type = Long 

Number of distinct values = as many as there are contiguous 
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blocks of un-allocated space in 
the TIFF file. 
Value range: (2**32) - 1 


The free offsets tag is a pointer to a group of pointers. Each of these pointers points 
to an available free contiguous area of space in the TIFF file. If there is only one free 
area of space, then there only need be one pointer. 


Note that this information is not useful for interchange purposes and is not recom- 
mended for TIFF writers and readers to use. 


4.8.2 The FreeByteCounts Tag 


FreeByteCounts 

Tag = 289 (121H) 

Type = LONG 

Number of distinct values = as many as there are contiguous 
blocks of un-allocated space in 
the TIFF file. 

Value range: (2**32) -1 


For each available contiguous block of space, the number of bytes available. Also, see 
comments for FreeOffsets. 
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5.1 Introduction 


It is helpful to review the role of files and file interchange in desktop publishing. As 
was covered in Chapter 1, desktop publishing can be divided into applications that 
produce the material for publishing, and those that combine the material, perform 
layout functions, and print the result. 


TIFF helps interchange data between applications that work primarily with bitmap 
graphics and applications that do layout and final printing. One way of talking about 
TIFF in this context is to speak about TIFF writers and TIFF readers. TIFF writers 
are applications that produce TIFF files with the intent that another application will 
read the TIFF file. TIFF readers are applications that merely read and interpret TIFF 
files. Of course, an application may do both, which allows even greater flexibility when 
interchanging files. 


With these ideas in mind, a key concern immediately arises. How does one insure that 
a TIFF file written by one application can be read by another application? This turns 
out to be straightforward for the majority of cases, and not straightforward for some 
cases. If a few guidelines are adhered to, then a given application is much more likely 
to succeed when interchanging TIFF data. However, it is still recommended that inter- 
change testing be done to verify that all guidelines have been appropriately followed. 


5.2 Guidelines for Writing TIFF Files 


When designing the code to write a TIFF file, a few ideas are important. First of all, 
writers should only use tag fields that describe information pertinent to the image 
being generated. For example, the fields "DocumentName, PageName, XPosition, 
and Y Position" may not be appropriate for the intended application. These tags 
probably don’t need to be included. However, the tags "XResolution" and 
"YResolution"” may be essential. 


Secondly, TIFF writers should stick to the defaults as much as possible. This is be- 
cause most TIFF readers only support the default options to conserve application 
memory usage. For example, although TIFF supports all 8 possible screen orienta- 
tions with the Orientation tag (Value 274), most readers of TIFF files only support the 
minimum default of a top, left orientation of the input page. Thus, for the orientation 
tag, a TIFF writer should stick to the default value of 1. 
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Although most readers will check tag values and even handle some of the non-default 
cases, TIFF writers should keep in mind that using default tag values make com- 
patibility easier to achieve. 


Finally, TIFF writers should keep private field usage to a minimum. (Again, private 
fields are values granted to an individual company by the TIFF administrator for 
private purposes.) If private fields are necessary, close coordination must be done 
with TIFF readers to get them to support the private tag field. 


5.3 Designing and Implementing a TIFF File Writer 


To design and implement a TIFF file writer, a few steps are recommended. First, 
decide which tags will be appropriate in describing your image application. (See 
Chapter 7 for a recommended set). Second, put together a sample small file on paper 
using the selected tag fields. Next, carefully study and modify the source code in- 
cluded in the Microsoft Windows Software Development Kit. Finally, debug and test 
the code, and exchange images with the intended TIFF reader(s). 


To select the appropriate tag fields, first identify the major bitmap image features 
your application supports (e.g., binary images, gray-scale images, and compressed bi- 
nary images). Then, for each data type, go through each of the tags and select those 
that seem to apply. Keep in mind the guidelines as described in the earlier section 
when making the selections, as well as the recommended tag list in Chapter 7. Again, 
it is probably best to include most of the tags and to set them to their default values 
(with the possible exception of the RowsPerStrip field). | 


Finally, in selecting the appropriate tag fields, check with the intended reader applica- 
tion. This should assist you in insuring compatibility. 


Once the tag fields have been selected, the next recommended step is to construct a 
sample file manually. (A worksheet for this purpose has been included in Chapter 7.) 
Many insights into the file format come by doing this exercise. To keep the file 
manageable, it is recommended that a small 10x10 pixel image be used for the actual 
data. (See the first file example in Chapter 3.) 


One way to build the file manually is to first block out the major sections on a 
diagram. This is to insure that all sections get put in and the pointers are allocated 
properly. (See sections 2.1-2.3.) Note that it is recommended that tag data informa- 
tion that requires a pointer (such as the X and Y resolution values) be located be- 
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tween the directory and the bitmap data. This makes it easier to design the header 
writing code. It is also recommended that the strip offset pointers and values be lo- 
cated after the raster data. This will make it easier to implement since the directory 
header for both the compressed and decompressed files will be the same length. 


Once the overall structure of the TIFF file has been designed, then fill in the ap- 
propriate tag fields in ascending order, leaving space for any offset values. These will 
be inserted later. After all the directory has been constructed, be careful to place in 
the terminating characters for a directory entry (four bytes of zero). Then, add any tag 
value fields that didn’t fit into the directory tag entries (X and Y resolution). Next, go 
back in and fill in the pointer values with the data locations. Fill in the sample bitmap 
data values (or the compressed data), and then place at the end of the file any strip of- 
fset pointers. 


To assist in testing your design, an actual TIFF file should be built using the DOS 
debug facility. DEBUG can be used to modify memory, and then the memory image 
can be saved as a file. The TIFF values are entered sequentially using the enter com- 
mand starting at location 0100. Then the BX:CX register pair are edited to be byte 
count of the file. Finally, the name command and write commands are used. (See the 
DEBUG instructions that come with the DOS manual.) This is a rather tedious 
process, but it is well worth the effort. (However, don’t try and enter a full page raster 
image! Use a 10x10 pixel image instead.) 


If you decide to build a sample file, a TIFF header reader program available from HP 
can be used to insure that the structure and information in the TIFF file is correct. 
Also, if the intended receiving application program with a TIFF reader is available the 
sample TIFF file can be used as a test case. 


Once the file has been manually designed, there are two alternatives for putting 
together code to implement the TIFF file format. The first alternative is to design 
your own software to write the information to a file. The second alternative is to make 
use of the sample C source code that is available from HP or Microsoft. Or, a com- 
bination of these two alternatives may be appropriate. 


The sample code for a TIFF writer, available in the Microsoft Windows Software 
Development Kit, is designed to write out a TIFF file with all the currently defined 
tags. It is a straightforward algorithm that takes as input a list of tags and values that 
are in a table and produces a TIFF file complete with dummy data. The intent of this 
code is that it be modified to include only the tags that you need to support. It can 
also be modified in other ways to match the architecture of your application. The 
source code has been commented thoroughly to make it easy to modify. 
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The code consists of four functions and a single data structure. The main function is 
used to write the image file header and dummy data to a file. It in turn uses three func- 
tions; one function to insert each new tag field into a directory, one function to insert 

a rational value into the header, and one function to insert actual pixel information 
into the TIFF file. 


A single data structure is used throughout the sample code which is defined in an in- 
clude file. This data structure is used to describe the desired image file. When going 
through the source code, it is handy to keep this structure available. In fact, if you 
decide to make use of the source code it is a good idea to fill in some sample values 
for this structure to serve as a guide when making modifications. 


As mentioned earlier, a sample TIFF header reader (C source code) is available from 
HP. This can be used to read any TIFF file header and directories. It will print out on 
the display the contents of the TIFF header and directories in an easy-to-understand 
fashion. This tool can be used to pre-test the output from the TIFF file writer before 
testing the file with actual reading applications. Note that it does not print out the ac- 
tual bitmap information on the display. Thus, its primary usefulness is in debugging 
the basic structure of the TIFF file, and in investigating other TIFF files for com- 
patibility experiments. 


5.4 Guidelines for TIFF Readers 


Readers of TIFF files have a trickier job for maximizing compatibility. A TIFF reader 
must decide on which tags and tag values to support, on how to handle unknown tag 
values, and on when to reject TIFF files as unreadable. 


First, a TIFF reader must decide on which tag and tag values to support. This re- 
quires an intelligent tradeoff between code space and flexibility. The most robust 
TIFF reader would be able to handle all known tag fields and tag values. This would 
require support for gray scale and color, as well as for both 68000 byte-order files as 
well as 8086 byte order files. The least robust TIFF reader would be able to handle 
only a small subset of the available tags. Of course, the least robust TIFF reader will 
not be able to handle as many different "TIFF" files as exist in the world. 


A TIFF reader should at least be able to handle all of the default tag values and 


recommended value ranges that exist in the current TIFF document. This will cover 
the majority of TIFF files in existence. 
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In addition, a TIFF reader should intelligently reject image files that might be likely to 
occur that can’t be supported by the application program. For example, a TIFF 
reader should check and see if the bit image is in color or has gray scale and potential- 
ly reject the file. Most of the tags in the pixel description group should be checked 
thoroughly by a TIFF reader code. 


A TIFF reader should ignore all tag fields that aren’t recognized, including private 
fields. Most private fields convey information-only data which is useful to only a small 
fraction of the applications programs. Further, public fields that convey information 
only about the file (such as an image description) can also be safely ignored. However, 
private data compression values must not be ignored. If they aren’t understood, then 
the file must be rejected. 


A TIFF reader shouldn’t assume that a tag written in the header has the default value. 
All tags should be checked to make sure that an appropriate value is used. This will 
aid in compatibility and interchange. For example, if the orientation tag is present in 
the header, the TIFF reader should check the tag and be sure that the value is 1 
before assuming the value is 1. Although this increases the code requirements some- 
what, it also insures that an end user won’t be frustrated when interchanging the file. 


Finally, a TIFF reader can make correct assumptions about the bitmap image for tags 
not present. TIFF writers are permitted to leave out tags that have a default value. 
Thus, any tag not present that has a default value defined can be assumed to be set to 
the default value. For example, the BitsPerSample tag has a default of 1. This indi- 
cates that the bitmap image was written with 1 bit / image pixel. If the BitsPerSample 
tag was not written in the header the reader can assume that BitsPerSample is 1. 


5.5 Designing and Implementing a TIFF File Reader 


Designing a TIFF file reader is similar to designing a TIFF file writer. The first step is 
to decide which fields and values to support, keeping in mind that the more flexibility 
is coded into the reader, the more likely that a given TIFF file can be read. Again, 
please refer to section 5.4 that described some recommendations for TIFF readers. 
To reiterate, it is recommended that at least all the default values for TIFF tags and 
values be supported and checked for compatibility purposes. Also, please refer to 
Chapter 7 for recommended TIFF fields to support for compatibility. 


Just as for a TIFF writer, determine the major bitmap images that your application 
supports (e.g., binary images, gray-scale images, and compressed binary images). 
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Once the supported tags and tag values have been decided upon, it is recommended 
that you obtain some sample TIFF files from the intended applications that write 
TIFF files. These files (as well as the sample files included with this document) should 
then be analyzed to be sure that all the features necessary will be supported by the 
TIFF reader and application code. They will also be useful when it comes time to 
debug the TIFF reader. 


The TIFF header reader available from HP can be used with TIFF files to decipher 
which tag fields and values are supported. This information can be useful when decid- 
ing on which tags and values to support. 


Once the decision has been reached about which tags and tag values will be sup- 
ported, it is recommended that some sample files be built using the procedures out- 
lined in section 5.2. This will help make some of the nuances of TIFF more apparent. 


Finally, the architecture design and implementation of the TIFF reader code can be 
done. There are two alternatives for doing this. The first alternative is to design your 
own software to read information from a TIFF file. The second alternative is to make 
use of the sample C source code that is available from HP or Microsoft. Or, a com- 
bination of these two alternatives may be appropriate. 


The sample source code for a TIFF reader is designed to read all defined public tags, 
and will read a few of the private tags. This information will be placed into a structure 
that holds all tag values. (This structure is defined in an include file). The intent of 
this code, as with the TIFF writer code, is that it be modified to include only the 
desired tags, and to match the appropriate application architecture. The source code 
has been commented to make such modification easy. 


5.6 Data Compression and TIFF 


TIFF has currently defined several compression schemes, including a packed form of 
data compression, and several variants of CCITT/3 compression. The packed form of 
compression 1s fairly straightforward, but the CCITT schemes requires some explana- 
tion. This section will focus on both the modified CCITT/3 i ia (compres- 
sion type 2) and the strip offset pointers used under TIFF. 


The primary task of data compression techniques is to discover and reduce redundan- 
cy in the data. In other words, data compression finds long runs of the same data 
values in the bitmap image and reduces the length of the data by substituting code 
words for the long run of data. For example, assume there is a row of bitmap informa- 
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tion that consists of 80 0’s in a row followed by 128 1’s (see figure 5.1). This would or- 
dinarily require 26 bytes of information, as each byte can hold 8 pixels of information 
if packed efficiently. However, if the "redundancy" of the data is taken into account, 
this same string of information can be expressed in just a few bytes. For example, we 
could represent this string as: 80 0 128 1 which would require only 4 bytes. 


Different compression techniques find and reduce redundancy in different fashions. 
Thus, different bitmap images (such as black and white, dither, gray-scale, and color) 
each require a different data compression algorithm. The goal of all compression tech- 
niques, however, is to express the most commonly encountered runs of data in the 
shortest possible compression codes. 


Most TIFF readers and writers uses a modified form of the standard CCITT/3 com- 
pression technique (compression type 2). This technique provides reasonable com- 
pression on black and white images that are 200 or 300 dpi. It doesn’t provide very 
good compression on dithered, gray-scale, or color images. Oftentimes, these images 
will expand when using CCITT/3 algorithms because the redundancy is not found in 
the same manner as for standard black and white images. 


80 0’S 128 1’S 26 BYTES 
00000...0 141197...1 
80,0 128,1 4 BYTES 
Figure 5.1 


The main CCITT/3 scheme used in TIFF (compression type 2) identifies continuous 
runs (called a run-length) of either all-white or all-black pixels. Each of these run- 
lengths is then replaced with a unique code word that can later be used to reconstruct 
the original continuous run of data. The unique code words are typically shorter than 
the continuous run of data that they are replacing (otherwise we would be doing data 
expansion rather than data compression!). 


This compression scheme uses two tables. One table contains code words for different 
continuous runs of white pixels from 0 through 63 pixels in length, and the other table 
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contains code words for the same continuous runs of black pixels. In addition, the 
tables contain values for some discrete run lengths above 63. If the white or black 
pixel run lengths exceed 63, then combinations of the code words above 63 and below 
63 are used to compress the longer run lengths. 


There are some further details necessary for understanding how to compress and 
decompress images. First, each row of the bitmap is compressed independently from 
any other row. Thus, each row of uncompressed data results in a row of compressed 
data. Secondly, each row must start with a white pattern, and must end on a byte 
boundary. Starting with a white pattern provides synchronization, and allows the 
decompression algorithm to know whether to search in the black run length table or 
in the white run length table. If the row starts with one or more black pixels, then a 
white run length of 0 pixels must start the row of compressed data code words. 


Note that the other CCITT compression schemes used in TIFF have different restric- 
tions. Please refer to the current TIFF document from Microsoft, and the CCITT 
documentation to see how these other techniques work. 


Let’s look at a simple example to see how both compression and decompression are 
done for the CCITT compression commonly used in TIFF files. This example consists 
of a single row of pixel information, consisting of 40 consecutive white pixels followed 
by 63 consecutive black pixels. First, the run of 40 consecutive white pixels is iden- 
tified and then replaced with the appropriate code word. In this case the appropriate 
code word is 00101001 (see the CCITT/3 white run length table). Then, the 63 con- 
secutive black pixels would be converted to the code word 000001100111 (see the 
CCITT/3 black run length table). Now, the code word that has been built up is 
00101001000001100111. This information must now be padded with zeros to be on a 
byte boundary. Thus, for this line of 103 pixels, the compressed data would be 
001010010000011001110000 or 29H, 06H, 070H. 13 uncompressed bytes have been 
replaced with 3 compressed bytes. This represents a compression ratio of 13/3 or 
about 4:1. 


To continue with this example, let’s focus on how the compressed string 29H, 06H, 
70H would be decompressed. The decompression algorithm would start comparing 
the string of compressed bit values, attempting to find a match in the white table 
(every row begins with a white code-word). When a match was found, then the cor- 
responding value would be output. In this case, the algorithm would try and first find 
0 in the white table, and then 00, and then 001, and then 0010 and so on until a match 
would be found when 00101001 was compared against the white table. In this case, 40 
zeros would be output as the decompressed data. Then, the algorithm would continue 
and try to first match 0, then 00, then 000, then 0000 and so on until 00000110011 
would match the entry in the table for 63 black pixels. The remaining 0000 would not 
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match anything in the table, and no data would be output. Note again how the white 
and black code words always alternate. 


As mentioned earlier, run lengths in the range from 64 to 2623 are encoded into a 
"make-up" code word representing the run length that is nearest to, but not longer 
than the actual run length. (The run-length codes above 63 aren’t continuous; see the 
TIFF CCITT/3 table.) Then, the make-up code word is followed by a terminating 
code word representing the remaining required number of bits for the original run- 
length. For example, if we have a run length of 420 white pixels, the make-up code 
closest (but not greater than) 420 is 384. The make-up code would be 00110111. For 
the remaining (420-384) or 36 white pixels, the code word would be 00010101. The en- 
tire code word for 420 white pixels would then be 0011011100010101. 


Run lengths greater than 2623 are coded by appending successive code words for 
2560 pixels together until the remaining part of the run becomes less than 2560 pixels. 
Then the procedures mentioned earlier are followed. 


Note that no EOL (end of line) markers are used in the above descibed CCITT com- 
pression scheme (compression type 2). These are common in CCITT/3 used for FAX. 
If EOL markers are used, the other CCITT schemes included in the TIFF specifica- 
tion must be used. 


Also note that the PhotoMetricInterpretation tag doesn’t apply when using CCITT 
compression. The values for white and black are predefined. This may require invert- 
ing all the binary data prior to encoding it into CCITT format. 


There are some additional details which are important to note when working with the 
standard CCITT compression scheme used in TIFF (compression type 2). Any pad- 
ding bits added to the uncompressed image row must not be compressed. Only com- 
press the length of data that was specified in the width tag field. For example, if a bit- 
map consisted of 10 pixels across, it would be stored uncompressed as 2 bytes across 
(so that each row would begin on a byte boundary). In this case, 6 padding bits would 
have been added. However, when compressing this information, only the first 10 bits 
should be considered as the data to be compressed, not the 6 padding bits. 


Data compression is a complicated topic. To help you save time and avoid many of 


the issues, it is recommended that existing compression source code be obtained to 
see how the mechanisms are implemented. 
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5.7 How to Improve Data Compression and Decompression 
Performance. 


Data compression and decompression save image storage space at the expense of 
having to spend more time accessing the images. It can take up to a minute to com- 
press a full 8 1/2 by 11 inch 300 dpi document. Thus, applications must guide a user 
into saving only the portions of an image that are really desired. In addition, clever al- 
gorithm design techniques can make data compression and decompression take less 
time. 


TIFF provides one mechanism that can make data decompression work more quickly 
under certain circumstances. This is done through the use of strip offsets (discussed 
in Chapter 4). 


For example, often it is important to extract only a given portion of the original image 
from the compressed data. For example, to convert a 300 dpi image for display to a 
screen, only every fourth row is needed. It is faster to only decompress every fourth 
row rather then every row. However, without a pointer mechanism, it isn’t possible 
using CCITT/3 to know where to start decompressing to obtain the fourth row of the 
original image. 


The TIFF writing application can divide the entire bitmap image into appropriately- 
sized strips. Each strip has an associated pointer and a count of compressed bytes in 
the strip. Further, each strip contains a known number of uncompressed bitmap rows. 
Thus, if the number of decompressed bitmap rows per strip is known, then the correct 
strip containing the data can be easily identified, and data decompression can start at 
a more appropriate place than at the beginning of the file. 


For the best compression speed, it is recommended that each strip consist of 1-10 
rows. However, it is still possible to get good results by providing a strip offset pointer 
for every 50 rows, beginning with the first row. Readers and writers are both en- 
couraged to use this mechanism if file access speed is important. Since not all applica- 
tions will provide this feature, it is best to design code that doesn’t require the addi- 
tional strip offset pointers but that can make use of them if they are available. 


It is advised to store the compressed bitmap contiguously so that multiple strip offsets 


aren’t needed. However, some writers will not store the different strips contiguously, 
which requires that the readers pay close attention to the strip offset pointers. 
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6.1 Introduction 


The TIFF file format was conceived by the Aldus company who first recognized the 
needs for standards in the desktop publishing industry. 


Many companies throughout the industry made excellent contributions to the TIFF 
format, including Dest, DataCopy, Microtek, HP, and Microsoft. Thus, it has really 
become an industry standard for desktop publishing. 


TIFF is a very flexible and expandable format, and will be undergoing extensions for 
some time. Microsoft has taken over support of the file format, and will be respon- 
sible for adding future changes to the file format. If you have any comments or sugges- 
tions about TIFF, get in touch with: 


Windows Marketing Group 
TIFF Administrator 
Microsoft Corporation 
16011 N.E. 36th Way 

Box 97107 

Redmond, WA 98073-9717 


In the future, it is likely that TIFF will support some additional compression schemes. 
Also, as we get more involved with gray scale and color, clarifications and expansions 
to some of the tag fields will probably be necessary. Desktop publishing is an exciting 
area, and is not likely to stand still for long! 
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7.1 Introduction 


This chapter includes some information that should be useful when building TIFF 
writer and reader applications. There are summaries of the fields, some worksheets 
that assist in designing TIFF files, and recommended tags and values to use for com- 
patibility. 


7.2 Summary Sheet of TIFF Tags 


Hex Name Value 
OFFH SubfileType Value: 
100H Image Width Value: 
101H ImageLength Value: 
102H BitsPerSample Value: 
103H Compression Value: 
106H PhotometriclInterp. Value: 
107H Thresholding Value: 
108H CellWidth Value: 
109H CellLength Value: 
10AH FillOrder Value: 
10DH DocumentName Value: 
10EH ImageDescription ASCil: 
10FH Make Ascii: 
110H Model Ascii: 
111H StripOffsets Value/Offset 
112H Orientation Value: 
115H SamplesPerPixel Value: 
116H RowsPerStrip Value; 
117H StripByteCounts Value/Offset 
118H MinSample Value Value: 
119H MaxSampleValue Value: 
11AH XResolution Value: 
11BH YResolution Value: 
11CH PlanarConfiguration Value: 
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pe 


11DH PageName Ascu: 

11EH XPosition Value: 

11FH YPosition Value: 

120H FreeOffsets Value/Offset: 
121H FreeByteCounts Value/Offset: 
122H GrayResponse Unit Value: 

123H GrayResponseCurve Value/Oftset: 
124H Group3Options Value: 

125H Group4Options Value: 

128H ResolutionUnit Value: 

129H PageNumber Value: 

12CH ColorResponseUnit Value: 

12DH ColorResponseCurves Value/Offset: 


7.3 Tiff File Design Worksheet 


Header 


_ 


Offset Value 


000 
001 
002 
003 
004 
005 
006 
007 


II. Directory 


Count: 
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Tag 1 
Tag 2 
Tag 3 
Tag 4 
Tag 5 
Tag 6 
Tag 7 
Tag 8 
Tag 9 
Tag 10 
Tag 11 


Tag 12 


III. 


Offset Tag 


| 
| 


Type 


End of directory 


Length 


Value/Offset 


Extended tag information (as needed) 


TIFF Miscellaneous 
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| 


IV. Raster data (as needed) 


PELL TLE TT 


VI. Strip byte counts (as needed) 


PELL 
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7.4 Recommended TIFF Tags and Values for Compatibility 


This section presents recommended tags and tag values for three different types of 
raster images. These include line-art/dither, compressed line-art, and gray-scale im- 
ages. The recommended tags and values assume images that have resolution of 300 
dpi. Other resolutions can be used, with the most commonly supported resolutions 
being 300, 200, 150, and 75 dpi. 


7.4.1 Tag Values for a Non-Compressed Line-Art/Dither Bitmap 


Name 


SubfileType 
ImageWidth 
ImageLength 
BitsPerSample 
Compression 


PhotometricInterp. 


Thresholding 
CellWidth 
CellLength 
FillOrder 
DocumentName 
ImageDescription 
Make 

Model 
StripOffsets 
Orientation 
SamplesPerPixel 
RowsPerStrip 
StripByteCounts 
MinSampleValue 
MaxSample Value 
XResolution 
YResolution 


PlanarConfiguration 


Value 

Value: 1 
Value: width 
Value: length 
Value: 1 
Value: 1 _ 
Value: 0 | 
Value: 

Value: 

Value: 
Value: 1 
Value: 

ASCii: 

ASCit: 

ASCil: 


Value/Offset: = Start of data 
Value: 1 


Value: 1 
Value: 
Value/Offset: 
Value: 0 
Value: 1 
Value:__300_ 
Value: 300_ 
Value: 1 
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PageName 
XPosition 
YPosition 
FreeOffsets 
FreeByteCounts 
GrayResponseUnit 


GrayResponseCurve 


Group3Options 
Group4Options 
ResolutionUnit 
PageNumber 


ColorResponseUnit 
ColorResponseCurves 


ASCil: 
Value: 
Value: 
Value/Offset: 
Value/Offset: 
Value: 
Value/Offset: 
Value: 
Value: 
Value: 
Value: 
Value: 
Value/Offset: 


Note: The resolution tags can be left out if resolution does not apply. When using 
dither techniques, the thresholding tag (107H) needs to be included and set to 2. 


7.4.2. Line-art with Compression Tags and Values 
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Hex 


OFFH 
100H 
101H 
102H 
103H 
106H 
107H 
108H 
109H 
10AH 
10DH 
10FH 
10FH 
110H 
111H 


Name 


SubfileType 
Image Width 
ImageLength 
BitsPerSample 
Compression 
PhotometricInterp. 
Thresholding 
CellWidth 
CellLength 
FillOrder 
DocumentName 
Image description 
Make 

Model 
StripOffsets 


Value 
Value: 1 _ 
Value: width 
Value: length 
Value: 1 
Value: 2 _ 
Value: 0 _ 
Value: 

Value: 

Value: 

Value: 1 
Value: 

ASCcil: 

Ascii: 

ASCII: 


Value/Offset: = Strip offsets 


EEE ELL Derr 


Orientation 
SamplesPerPixel 
RowsPerStrip 
StripByteCounts 
MinSample Value 
MaxSampleValue 
XResolution 
YResolution 
PlanarConfiguration 
PageName 

X Position 
YPosition 
FreeOffsets 
FreeByteCounts 
GrayResponse Unit 
GrayResponseCurve 
Group3Options 
Group4Options 
Resolution Unit 
PageNumber 
ColorResponseUnit 
ColorResponseCurves 
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Value: 1 
Value: 1 
Value:_ OAH_ 


Value/Offset: = Strip byte counts 
Value: 0 


Value: 1 
Value: 300_ 
Value: 300_ 
Value: 1 
Ascil: 

Value: 

Value: 
Value/Offset: 
Value/Offset: 
Value: 
Value/Offset: 
Value: 

Value: 

Value: 

Value: 

Value: 
Value/Offset: 


Note: The resolution tags can be left out if resolution does not apply. Rows per strip 
is recommended to be either 2 or 1. This will speed the time it takes to read and 
create a reduced-resolution mage. Also, notice that CCITT/3 data compression does 
not apply for dithered images (it usually causes them to expand rather than compress). 


7.4.3. 4-bit Gray-scale Tags and Values 


Hex 


OFFH 
100H 
101H 
102H 
103H 


Name 


SubfileType 
ImageWidth 
ImageLength 
BitsPerSample 
Compression 


Value 
Value: 1 
Value: width 
Value: length 
Value: 4 | 
Value: 1 
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106H 
107H 
108H 
109H 
10AH 
10DH 
10EH 
10FH 
110H 
111H 
112H 
115H 
116H 
117H 
118H 
119H 
11AH 
1iBH 
11CH 
11DH 
11EH 
11FH 
120H 
121H 
122H 
123H 
124H 
125H 
128H 
129H 
12CH 
12DH 


PhotometricInterp. 
Thresholding 
CellWidth 
CellLength 
FillOrder 
DocumentName 
ImageDescription 
Make 

Model 
StripOffsets 
Orientation 
SamplesPerPixel 
RowsPerStrip 
StripByteCounts 
MinSampleValue 
MaxSampleValue 
XResolution 
YResolution 


PlanarConfiguration 


PageName 
XPosition 
YPosition 
FreeOffsets 
FreeByteCounts 
GrayResponseUnit 


GrayResponseCurve 


Group3Options 
Group4Options 
ResolutionUnit 
PageNumber 


ColorResponseUnit 
ColorResponseCurves 


Value: 0 | 

Value: 

Value: 

Value: 

Value: i | 

Value: 

ASCIL 

Ascii: 

Ascil: 

Value/Offset: = Start of data 
Value: 1 


Value: 1 
Value: 
Value/Offset: 
Value: 0 
Value: 15_ 
Value:__ 300 
Value:__ 300 
Value: 1 
ASCU: 

Value: 

Value: 
Value/Offset: 
Value/Oftset: 
Value: 2 
Value/Offset:Offset 
Value: 

Value: 
Value: 
Value: 

Value: 
Value/Offset: 


Note: The resolution tags can be left out if resolution doesn’t apply. The peripheral 
manufacturer will need to provide the values for the response curves from the gray- 
scale imaging device (scanner or camera). 
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Windows Dynamic Data Exchange 


8.1 Introduction 


Microsoft Windows provides DOS with a graphic user interface and a form 
of multitasking. It allows messages and data to be sent between different 
applications by using the Dynamic Data Exchange (DPE) protocol. For 
instance, communication can be set up between two applications so that 
one sends updated data to the other as soon as the data becomes avail- 
able. This chapter gives an example of this sort of communication, which 
is called a “conversation.” | 


8.2 The Windows 


Communications Capability 


This section explains how Windows allows easy implementation of the 
DDE protocol. No changes are required to the current or previous versions 
of Windows to make use of DDE. 


Windows allows flexible inter-task communication. The primary means of 
communication is passing messages. Windows applications receive all 
input in the form of messages. All characters typed at the keyboard, all 
mouse activity, and all menu selections are sent to the appropriate Win- 
dows application through messages. A Windows application has a message 
loop that continually requests messages from the system and then 
processes them. 


In Windows, applications may define private messages that have a unique 
meaning throughout the system. In addition, the DDE protocol defines 
one new messages that allow communication between the applications 
that use it. | 


Windows also provides sharing of data between applications. The DDE 
protocol, which uses shared memory to transfer data from application to 
application, defines structures to hold the contents of the shared memory. 


8.3 Uses for Windows 
Dynamic Data Exchange 


The examples in this chapter are only a few of the ways to use DDE. These 
are also only ideas; they do not represent a commitment on the part of 
Microsoft Corporation or Lotus Development Corporation to provide these 
features in any application. 
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Potential uses of DDE abound in real-time data acquisition. What follows 
is a DDE-based, real-time, portfolio tracking system. In this example, 
there are two hypothetical Windows applications cooperating. One is an 
interface application that takes data from a Lotus Signal FM Sideband 
receiver and the other is a spreadsheet application. Both applications use 
the DDE protocol. In the DDE exchanges that follow, the spreadsheet 
application is the client—that is, the application that initiates DDE 
transactions—and the Signal interface application is the server that 
responds to DDE transactions. 


The example spreadsheet has the following layout: 


A B C D 
1 Stock Shares Price Extension 
2 IBM 1000 120 155000 
3 LOTS 2000 20 80000 
4 TATE 200 20 7000 
5 MSFT 2000 50 76000 
6 318000 


Without DDE, this spreadsheet could be updated by using Clipboard to 
manually copy numbers from the Signal application screen into the 
spreadsheet. This would require screen-sharing or switching between appli- 
cations and would require that the user pay attention to the price data 
and decide when to exchange data. 


With DDE, this system could be much more automatic, providing the 
spreadsheet with the current values for multiple data items without inter- 
vention by the user. DDE would allow the user to set up a conversation 
between the server and client applications that would inform the 
spreadsheet of any changes in the values of the stocks it has asked about. 


A simple user interface would allow the spreadsheet to provide for external 
references in cell formulas; these references could retrieve data from 
another application through DDE. The following is a possible syntax for 
such an external reference: 

= Application ! Topic ! Item 

In this spreadsheet, it might be as follows: 

= SIGNAL } NYSE ! IBM 

This indicates that the cell content is to be the value of the data item 


“TBM” on the topic “NYSE” of the application “SIGNAL”. 
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Once this connection had been established, the cell value would always 
reflect the most current data available from the server. No per-transfer 
intervention on the user’s part would be necessary. This would facilitate 
the analysis of real-time data in a timely manner. 


The usefulness of DDE is not restricted to specialized real-time data 
acquisition. Productivity software in general can benefit from the protocol. 
For example, suppose a report is to be prepared monthly, using a graphics- 
and-text word processor. The report is to include graphs generated in a 
separate business-graphics package. Without DDE, it would be necessary 
to go through a manual copy-and-paste process to include each month’s 
new graphs in each month’s report. With DDE, the word processor can 
establish a permanent link to the charting application, so any changes 
made to the charting document are reflected in the word-processing docu- 
ment, elther automatically or on request. This makes routine report 
preparation much simpler. 


8.4 Inside DDE: 
Workings of the Protocol 


This section, which presents a more detailed view of the workings of the 
DDE protocol, further discusses the example of the Signal/spreadsheet 
interaction, illustrating the forwarding of stock quotes from the Signal 
interface application to the spreadsheet. For simplicity, the example is 
limited to the exchange of quotes for a single stock, IBM. 


The Signal DDE server application is started first. Typically, applications 
designed to operate as dedicated DDE servers have some sort of user inter- 
face for initialization and then run as icons at the bottom of the Windows 
screen. As part of the initialization process, the Signal DDE server applica- 
tion goes through whatever steps are necessary (entering passwords, tun- 
ing, testing, and so forth) to insure that reception is good and that data 
can be provided to clients. 


The spreadsheet is started next, and the stock portfolio worksheet is 
loaded. At this time, the spreadsheet broadcasts a WM. DDE _ INITIATE 


message to all currently running applications. 


The broadcast message is a request to initiate a conversation with the 
application called “SIGNAL” on the topic called “NYSE”. An application 
receiving such a request can accept it by responding with a positive | 

WM_ DDE_ ACK message or can decline it by not responding. If no appli- 
cation accepts the request, the spreadsheet would assign an error value to 
the external reference, and its DDE activity would conclude. In this exam- 
ple, it is assumed that the currently running Signal application accepts the 
request, and a DDE conversation is established between the two applica- 
tions. 
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The spreadsheet can now use the newly established conversation to ask the 
Signal application for continuous updates on the specific datum it needs. 
To do so, it sends a WM_ DDE_ ADVISE message to the Signal applica- 
tion, indicating that it wants updates sent every time there is a new value 
for the data item named “IBM”, and that it wants the updates in text for- 
mat (CF_ TEXT). 


Upon receiving this message, the Signal application makes a note of the 
request in its database and sends a WM_ DDE_ ACK message to the 
spreadsheet. From then on, whenever it receives a new IBM stock quote 
from the Signal receiver, the Signal application sends a WM_ DDE_ DATA 
message to the spreadsheet application. Each of these messages carries the 
handle of a shared memory object; the object itself contains the 
corresponding stock quote, rendered in the requested format. Whenever 
the spreadsheet receives such a message, it retrieves the corresponding 
stock-quote data from the referenced memory object, and uses the data to 
update the value of the cell that contains the external reference. 


The periodic updates continue until the spreadsheet’s worksheet is closed. 
At that point, the spreadsheet application sends a WM_..DDE_ UNADVISE 
message to the Signal application, indicating that further updating is not 
necessary. Upon receiving this message, the Signal application removes the 
corresponding data request from its database and returns a positive 


WM_ DDE_ ACK message to the spreadsheet. 


Finally, unless it wishes to initiate other data exchanges under the 
“NYSE” topic, the spreadsheet sends a WM_ DDE_ TERMINATE message 
to the Signal application, indicating the end of the DDE conversation. The 
Signal application responds with a WM. DDE~ TERMINATE message. 


This is a simple example of how the protocol can be used. A full descrip- 
tion of the protocol’s message sequences, the content of messages, and the 
makeup of shared memory objects is contained in Chapter 9, “Windows 
DDE: Rules of the Road,” and Chapter 10, “Windows DDE: Protocol 


Definition.” 
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9.1 Introduction 


This chapter contains technical guidelines and implementation tips for 
developers of Microsoft Windows applications who wish to take advantage 
of the Windows Dynamic Data Exchange (DDE) facility. 


This chapter is divided into seven sections: 


e Terminology and Basic Rules 

e DDE Transaction Reference 

e Synchronization Rules 

e Atom Allocation Rules 

e ‘Shared Memory Object Rules 

e Syntax of the EXECUTE Command String 
e The System Topic 


9.2 ‘Terminology and Basic Rules 


Throughout this chapter, the term “application” is used to denote a Win- 
dows task; that is, a particular running instance of an application. 


DDE is a protocol that allows applications to exchange data on a real-time 
basis. To perform such an exchange, the two participating applications 
first have to engage in a DDE conversation. The application that initiates 
the conversation is known as the client application, and the application 
responding to the client 1s known as the server application. A given appli- 
cation can be engaged in several conversations at the same time, acting as 
a clhent application in some and as a server application in others. 


A DDE conversation between two applications actually takes place 
between two windows, one for each of the participating applications. 
Applications open a window for each conversation they engage in. (Note 
that such windows are not typically visible.) A window is identified by its 
handle, hWnd. The window belonging to the server application is the 
server window; the window belonging to the client application is the client 
window. 


DDE uses a three-level hierarchy of item, topic, and application to 
uniquely identify a unit of data. An item is a data object that can be 
passed in a DDE data exchange. For example, an item might be a single 
integer, a string, several paragraphs of text, or a bitmap. A topic is a logi- 
cal data context. For applications that operate on file-based documents, 
topics are usually filenames; for other applications, they are other 
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application-specific strings. Since each window represents an application’s 
conversation on a single topic, the window handle, hWnd, identifies both 
application and topic. 


Several server windows can be associated with the same topic at the same 
time. Also, a given window can participate either as server or as client in 
several conversations on the same topic at the same time. 


After a conversation has been started, the client interacts with the server 
by issuing transactions. When issuing a transaction, the client is asking 
the server to perform a given action. There are six types of transactions: 
REQUEST, ADVISE, UNADVISE, POKE, EXECUTE, and TERMINATE. 
These are permitted only after a conversation has been initiated with an 
INITIATE message. DDE conversations are one-way: the client application 
is always the one that issues a transaction. If the server wishes to issue a 
transaction to the client, the server is expected to initiate a new conversa- 
tion for that purpose. The server will become the client in this new conver- 
sation. (The only exception to the one-way rule is the TERMINATE tran- 
saction, which can be issued by either the client or the server.) 


The INITIATE message and its corresponding ACK message are issued by 
using the Windows SendMessage function. All other messages are issued 
by using the Windows PostMessage function. 


9.3 DDE Transaction Reference 


The following sections are divided into five parts, each covering one of the 
basic types of interchange supported by DDE: 

e Initiation of a conversation 

e One-time data transfer 

e Permanent data link 

e Execution of commands in a remote application 

e Termination of a conversation 


Each provides a detailed description of the specific message protocols asso- 
ciated with the transactions it encompasses. 
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9.3.1 Initiating a Conversation 
Between Two Applications 


To initiate a DDE conversation, the client broadcasts an INITIATE mes- 
sage as follows: 


SendMessage(-1, WM_DDE_INITIATE, hwndClient, 
MAKELONG (aApplication, aTopic)) 


The SendMessage parameters mean the following: 


e Windows, as specified by the -1 parameter, will send this message 
to all other active applications. The SendMessage function will 
not return to the client application until all receiving applications 
have, in sequence, returned control to Windows. 


e The aApplication parameter identifies the desired server applica- 
tion. The aTopic parameter identifies the desired topic of conversa- 
tion. The aApplication and aTopic atoms can be left NULL by the 
client application. 


e The MAKELONG macro combines the aApplication and aTopic 
atoms into a long word (32 bits). 


Server applications will respond as in the following example: 


If ((specific app requested and server is instance of app) 
or (specific app not requested) ) 
If (specific topic requested) 
If (server can support topic) 
Ack the requested topic 
Else 
Ack each supported topic 


To acknowledge the requested topic, the server responds with: 


SendMessage (hwndClient, WM_DDE_ACK, hwndServer, 
MAKELONG (aApplication, aTopic)) 


To acknowledge each supported topic, the server makes one response for 
each topic it is willing to support. This initiates a conversation on each 
topic; the client is expected to terminate all unwanted conversations. 


Note 


The server must re-add the atoms for each ACK message it sends; see 
Section 9.5, “Atom Allocation Rules,” for details. 
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9.3.2 One-Time Data Transfer 
Between Two Applications 


A client application can use DDE to obtain a data item from a server : 
(REQUEST), or to submit a data item to a server (POKE). a 


9.3.2.1 The REQUEST Transaction 


The client sends the server a REQUEST message specifying the desired 
item and format as follows: 


PostMessage (hwndServer, WM_DDE_REQUEST, hwndClient, 
MAKELONG (cfFormat, alItem) ) 


If the server has access to the required item and can render it in the 
correct format, the server renders the item as a global shared memory 
object (see Chapter 10, “Windows DDE Protoco! Definition,” for object 
layout) and sends the client a DATA message as follows: 


PostMessage (hwndClient, WM_DDE_DATA, hwndsServer, 
MAKELONG (hData, alItem)) 


If the server is unable to satisfy the request, it sends the client a negative 
ACK message, as follows: 


PostMessage (hwndClient, WM_DDE_ACK, hwndServer, 
MAKELONG (wStatus, altem) ) 


Upon receiving a DATA message, the client processes the data item as 
appropriate. Then, if the fAck bit for the item is 1, the client is expected 
to send the server a positive ACK message as follows: 


PostMessage (hwndServer, WM_DDE_ACK, hwndClient, 
MAKELONG (wStatus, alItem) ) 


Upon receiving a negative ACK message, the client may ask for the same 
item again, specifying a different clipboard format. Typically, a client will 
first ask for the most complex format it can support, then step down if 
necessary through progressively simpler formats until it finds one the 
server can provide. 


9.3.2.2 The POKE Transaction oie 


The client renders the item to be sent in the format of its choice, and 
sends the server a POKE message, as follows: 


PostMessage (hwndServer, WM_DDE_POKE, hwndClient, 
MAKELONG (hData, altem) ) 
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If the server is able to accept the data item and the format in which it is 
rendered, the server processes the item as appropriate and sends a positive 
ACK message. If it is unable to process the item due to format or other 
reasons, the client sends a negative ACK message. These positive and 
negative ACK messages take the following form: 


PostMessage (hwndClient, WM_DDE_ACK, hwndServer, 
MAKELONG (wStatus, altem)) 


9.3.3 A Permanent Data Link 
Between Two Windows Applications 


A client application can use DDE to establish a link to an item in a server 
application. When such a link is established, the server sends periodic 
updates of the linked item to the client (typically, whenever the data asso- 
clated with the item in the server application has changed). Thus, a per- 
manent data stream is established between the two applications and 
remains in place until it is explicitly disconnected. 


9.3.3.1 The ADVISE Transaction (Establishing the Link) 
The client sends the server an ADVISE message as follows: 


PostMessage (hwndServer, WM_DDE_ADVISE, hwndClient, 
MAKELONG (hOptions, aItem) ) 


If the server has access to the requested item and can render it in the 
desired format, the server notes the new link (remembering the flags 
specified in hOptions), and sends the client a positive ACK message. From 
then on, until the client issues a matching UNADVISE transaction, the 
server executes a DATA UPDATE sequence every time the source data 
associated with the item in the server application changes. 


If the server is unable to service the request, it sends the client a negative 
ACK message. 

9.3.3.2 The DATA UPDATE Sequence 

For links established with fNoData=0, the client has requested that the 
data be sent each time it changes. In such cases, the server renders the new 
version of the item in the previously specified format, and sends the client 


a DATA message as follows: 


PostMessage (hwndClient, WM_DDE_DATA, hwndServer, 
MAKELONG (hData, altem))- 
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The client processes the item as appropriate. If the fAck bit for the item is 
1, the client sends the server a positive ACK message. 


For links established with fNoData equal to 1, the client has requested 
that only a notification, not the data itself, be sent each time the data 
changes. In such cases, when the source data changes, the server does not 
render the new version of the item, but simply sends the client a DATA 
message with a null data handle as follows: 


PostMessage (hwndClient, WM_DDE_DATA, hwndServer, 
MAKELONG (null, alItem)) 


At its discretion, the client can then request the latest version of the data 
by performing a regular REQUEST transaction, or it can simply ignore the 
data-change notice from the server. In either case, if fAck is equal to 1, the 
client is expected to send a positive ACK message to the server. 


9.3.3.3 The UNADVISE Transaction 
(Terminating the Link) 


If the client wishes to terminate a single specific link, the client sends the 
server an UNADVISE message, as follows: 


PostMessage (hwndServer, WM_DDE_UNADVISE, hwndClient, 
MAKELONG (null, alItem)) 


The server checks whether the client currently has a link to the specified 
item in this conversation. If so, the server sends the client a positive ACK 
message and is then no longer responsible for sending updates about the 
item in this conversation. If the server has no such link, it sends a negative 
ACK message. 


If the client wishes to terminate all links for a particular conversation, the 
client sends the server an UNADVISE message as follows: 


PostMessage (hwndServer, WM_DDE_UNADVISE, hwndClient, 
MAKELONG (null, null) ) 


The server checks whether the conversation has at least one link currently 
established. If so, the server sends a positive ACK message and is then no 
longer responsible for sending any updates in the conversation. If the 
server has no links in the conversation, it sends a negative ACK message. 
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9.3.4 Executing Commands 
in a Remote Application 


A Windows application can use DDE to cause a certain command or series 
of commands to be executed in another application. Such remote execu- 
tions are performed by means of the EXECUTE transaction. 


The client sends the server an EXECUTE message containing a handle to 
a command string as follows: 


PostMessage (hwndServer, WM_DDE_EXECUTE, hwndClient, 
MAKELONG (null, hCommands) ) 


The server attempts to execute the specified string. If successful, the server 
sends the client a positive ACK message; if unsuccessful, a negative ACK 
message. These messages are of the following form: 


PostMessage (hwndClient, WM_DDE_ACK, hwndServer, 
MAKELONG (wStatus, hCommands) ) 


See Chapter 10, “Windows DDE Protocol Definition,” for a complete 
definition of the flags to be set in wStatus. 


9.3.5 Terminating a Conversation 
Between Two Applications 


Either client or server may issue a TERMINATE message to terminate a 
conversation at any time. Similarly, both client and server applications 
should be prepared to receive a TERMINATE message at any time. An 
application must terminate all of its conversations before shutting down. 


aie application wishing to terminate sends a TERMINATE message as 
ollows: 


PostMessage (hwndRecipient, WM_DDE_TERMINATE, hwndSender, 
MAKELONG (null, null)) 


This constitutes a promise to send no further messages, and confers per- 
mission for the recipient to close its window (destroy its hWnd). The reci- 
pient is expected in all cases to send a TE NATE message promptly in 
response; it is not permissible to send a negative, busy, or positive ACK 
message. 


If the original sender receives any other message before TERMINATE, no 


response must be sent, as the sender of that other message might already 
have destroyed the window that the response would be sent to. 
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9.4 Synchronization Rules 


A window that is processing DDE requests from another window must pro- 
cess them strictly in the order in which the requests were received. A win- 
dow does not need to apply this first-in, first-out rule to requests from 
different windows, which means it may provide asynchronous support for 
multiple processes. For example, suppose a window has the following 
requests in its queue: 


#1: Message from window x 
#2: Message from window y 
#3: Message from window x 


The window must process #1 before #3, but it does not need to process 
#2 before #3. It may decide that y is a lower priority client than x, and 
therefore follow the order #1, #3, #2. 


If a server is unable to process an incoming request because it is itself 
waiting for an external process, it must post a busy ACK message to the 
client, to prevent deadlock. A busy ACK message may also be sent if the 
server expects for any reason to be unable to process an incoming request 
within a reasonable length of time. 


9.5 Atom Allocation Rules 


Certain arguments of DDE messages (altem, aTopic, and aApplication) are 
global atoms. In order for old atoms to be purged from the atom list, they 
have to be explicitly deleted by the applications using them. The following 
set of rules ensures that such deletions are performed correctly, and that 
the atom manager operates smoothly. 


Note 


In Windows 1.02, atom-management services are made available 
through calls to a dynamically-linked library dde.exe. In Windows 2.02, 
these services are provided by Windows itself. 
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9.5.1 Responsibilities of the Message Sender 


The application that sends a DDE message is expected to add the atoms 
contained in the message. The exception is the following: 


e WM_DDE_ ACK sent in response to a DATA, REQUEST, POKE, 
ADVISE, or UNADVISE message. In these situations the sender 
may either reuse the atom that came with the original message or 
else delete and re-add it. 


The sender does not typically delete atoms. The exceptions to this rule are 
the following: 


e The atoms in WM_DDE_INITIATE, which the sender is expected 
to delete when the call to the SendMessage function returns. 


e The atom(s) in other messages when an error condition occurs 
(such as when a PostMessage function fails) and the sender is cer- 
tain that the receiver will not process the corresponding message. 
In such cases the sender is expected to delete the atom(s) of the 
unsuccessful message. 


9.5.2 Responsibilities of the Message Recipient 
The application that receives a DDE message containing a global atom is 


expected to handle the atom(s) according to the following rules, depending 
on which message has been received: 


Message Received Action Taken 

WM_ DDE_ INITIATE No action. 

WM_ DDE. REQUEST No action. 

WM_ DDE. POKE No action. 

WM_ DDE ADVISE No action. 

WM. DDE_ UNADVISE No action. 

WM. DDE_ DATA If no ACK message is requested, receiver 
should delete atom. 

WM... DDE ACK Receiver is always expected to delete 
atom(s). 

WM_ DDE_ EXECUTE No atom involved. 


WM. DDE_ TERMINATE No atom involved. 
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The exception to these rules is the following: 


e An application that is waiting for a TERMINATE message (having 
itself sent a TERMINATE message) may receive other messages 
that would ordinarily require an ACK message in response. It may 
not send an ACK message at such times, however, and so is obli- 
gated to delete any atoms involved. 


f 


9.6 Shared Memory Object Rules 


DDE uses shared memory objects for three purposes: 


e Tocarry a data item to be exchanged (item referenced by hData in 
WM. DDE. DATA and WM_ DDE_ POKE) 


e To carry options in a message (item referenced by hOptions in 


WM_ DDE_ ADVISE) 


e Tocarry an execution command string (item referenced by hCom- 

mands in WM_ DDE_ EXECUTE and its corresponding 

WM_ DDE_ ACK) 
All shared memory objects in DDE are to be treated as read-only by their 
recipients. This prohibits their use as mutual read/write areas for the free 
exchange of information. 
As with DDE atoms, shared memory objects need to be freed properly in 
order for the memory manager to be effective. Shared memory objects also 
need to be properly locked and unlocked. 
aa following sections specify rules for the proper handling of memory 
objects. 


9.6.1 Responsibilities of the Message Sender 

The sender allocates a DDE shareable object as follows: 

GlobalAlloc (GMEM_MOVEABLE |! GMEM_DDESHARE, dwbytes) 

Note that GMEM_ DDESHARE is a new flag with a value equal to 0x2000. 
The object is then locked using the GlobalLock(hmem) function, and ini- 


tialized with the data to be sent. The object is then unlocked by using the 
GlobalUnlock(hmem) function. At this point the message is sent. 
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In general, the application that sends a DDE message containing a shared 
memory object does not free the object. There is one exception: 


e If an error condition occurs (such as when a PostMessage func- 
tion fails), then the sender should free the shared memory object. 


9.6.2 Responsibilities of the Message Recipient 


The application that receives a DDE message referencing a shared memory 
object must handle the object according to the following rules: 


e The object must, be locked before it can be read. The recipient 
must be prepared for the lock to fail, because of network or 
Expanded Memory considerations. If the lock fails, the recipient 
should free up memory and try the lock again. 


e After reading the memory object, it must be unlocked. Once the 
object is unlocked, the recipient should proceed as follows, depend- 
ing on which message has been received: 


Message Received Action Taken 
WM. DDE. DATA If fRelease is equal to zero, or if fRelease fAck 


are equal to one and the operation did not 
succeed), the recipient of the DATA message 
must not free the object. Otherwise, it must 
free the object. 


WM_ DDE. POKE If fRelease is equal to zero, or if fRelease is 
equal to one and the operation did not 
succeed), the recipient of the DATA message 
must not free the object. Otherwise, it must 
free the object. 


WM. DDE_ ACK In reply to WM_ DDEW DATA or WM_ DDE_- 
POKE, recipient of this ACK message must 
free the previously sent object referred to by 
altem if it was sent with fRelease equal to zero, 
or if the ACK message is negative or busy. 


Note 
If a DATA or a POKE message is sent with both fRelease and fAck 


equal to zero, the recipient will neither send an ACK message nor 
release the object. Thus, the sender must release the memory object at 
the appropriate time. In general, it is not recommended that fRelease 


and fAck both be zero. 
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WM. DDE ADVISE If the ADVISE is successful, the recipient must 
free the object. Otherwise, it must not free the 
object. 


WM_ DDE_ ACK In reply to WM~ DDE_ ADVISE, the recipient 
of this ACK message must free the previously 
sent object referred to by altem if the ACK 
message is negative or busy. 


WM_DDE_ EXECUTE  Inreply to WM_ DDE_ EXECUTE, the reci- 
pient of WM_DDE_ ACK message must free 
the object. Otherwise, the recipient must not 
free the object. 


9.7 Syntax of the EXECUTE 


Command String 


DDE provides a means of delivering command strings from a client appli- 
cation to a server application by using an EXECUTE message. 


An EXECUTE command string is null-terminated. It is recommended that 
such strings obey the following syntax: 


execute string:= tokentoken...token 
token:= lbracketopcode stringrbracket 
lbracket:= [ 


rbracket:= | 


opcode string:= opcode opcodeparameter list 


opcode:= application-defined single token; may not include spaces, 
commas, parentheses, or quotes 


— parameter itsts== lparenparameter, parameter....,parameterrparen 
lparen:= ( 


rparent= ) 


parameters= application-defined; may not include commas or 
parentheses except inside a quoted string. 
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Quoted characters:= "[","]","(", and")" must be doubled if they are to appear as 
characters within opcode.string. 


Example EXECUTE Strings: 


[connect] [download (query1, results.txt) ] [disconnect] 
[query ("sales per employee for each district")] 


[open ("foo.xlm")] [run ("“ricl") ] 


9.8 The System Topic 


Applications are encouraged to support at all times a special topic with 
the name “System”. This topic provides a context for items of informa- 
tion that may be of general interest to an application. 


The following items are suggested (this list is not exclusive): 

Item Description 

SysItems A list of the items supported under the System topic 
by this application. 


Topics A list of the topics supported by the application at the 
current time (this may vary from moment to moment). 


ReturnMessage Supporting detail for the most recently issued ACK 
message. Useful when more than 8 bits of application- 
specific return code are required. 


Status An indication of the current status of the application. 


Formats This item contains a list of clipboard-format numbers 
that the application can render. 


Individual elements of such lists should be delimited by tabs (CF_TEXT 
format). 
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10.1 Introduction 


There are two components to the Microsoft Windows Dynamic Data 
Exchange ee protocol: a set of new Windows messages devoted to DDE 
and several new Clipboard data formats. 


The protocol uses nine messages whose purpose and parameters are 
described in this chapter. The descriptions give a only a limited indication 
of how to organize the conversation between applications; a more complete 
discussion of that topic is contained in Chapter 9, “Windows DDE: Rules 
of The Road.” 


Conventions Used in This Chapter 


Parameter names bear prefixes indicating their type, as follows: 


Prefix Description 

a An atom of word length (16 bits); for example, aName. 

h A handle (word length) to a global memory object; for example, 
hName. 7 

cf A registered clipboard format number (word length); for exam- 
ple, cfFormat. 

Ww Any other word-length parameter; for example, wName. 

f A flag bit; for example, fName. 


10.2 The DDE Message Set 


Fach DDE message has two parameters. The first parameter, wParam 
(word length), carries the handle of the sender’s window; it is the same in 
all cases and so is not shown in Table 10.1. The second parameter, [Param 
(a long word, 32 bits), is composed of a low-order word and a high-order 
word, as follows: 
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Table 10.1 
DDE Messages 
Arguments in [Param 
Message Low-order word High-order word 
WM_ DDEW INITIATE aApplication aTopic 
WM_DDE_ TERMINATE — (Reserved) (Reserved) 
WM_ DDE_ ACK 
In reply to INITIATE aApplication aTopic 
In reply to EXECUTE wotatus hCommands 
All other messages wotatus altem 
WM_ DDE_ REQUEST efFormat altem 
WM. DDE. DATA hData altem 
WM. DDE_ ADVISE hOptions altem 
WML_ DDE_ UNADVISE (Reserved) altem 
WM_ DDE_ POKE hData altem 
WML_ DDE_ EXECUTE (Reserved) hCommands 


These messages are passed by using the SendMessage and PostMessage 
functions. The handle, hWnd, of the addressee window appears as the first 
parameter of these calls; for example: 


PostMessage (hwndRecipient, WM_DDE_MESSAGE, hwndSender, 
MAKELONG (low_word, high_word) ) 


The MAKELONG macro combines low_ word and high word into a long 
word. 


WM_ DDE_ INITIATE 


This message is sent by an application to one or more other applications, 
to request initiation of a conversation. 


Upon receiving this message, all applications with names that match the 
aApplication application and that support the topic aTopic are expected 
to acknowledge (see the WM_ DDE_ ACK message). 


Application names may not contain slashes or backslashes. These charac- 
ters are reserved for future use in network implementations. 
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Parameter Description 


aApplication Low-order word of [Param. An atom that 
specifies the name of the application to service 
the request. 


a Topic High-order word of |Param. An atom that 
specifies the required topic. 


If the aApplication parameter is NULL, any application may respond. If 
the aTopic parameter is NULL, any topic is valid. Upon receiving an INI- 
TIATE request with a null topic, an application is expected to send an 
ACK message for each of the topics it supports. 


WM_ DDE_ TERMINATE 


This message is sent by either application participating in a DDE conver- 
sation to terminate that conversation. 


Upon receiving this message, an application is expected to send a TER- 
MINATE message in response. 


The low-order and high-order words in [Param are reserved. 


WM_ DDE_ ACK 


This message notifies an application of the receipt and processing of a 
WM_ DDE_ INITIATE, WM_ DDE. EXECUTE, WM_ DDE_ DATA, 

WM_ DDE” ADVISE, WM_ DDE_ UNADVISE, or WM_ DDE_ POKE mes- 
sage, and in some cases, of a WM. DDE_ REQUEST message. 


Parameters vary according to context, as follows: 


Parameters Description 

aApplication Low-order word of |Param, if replying to 
WM_ DDE_INITIATE message. 

aTopic High-order word of lParam, if replying to 
WM. DDE_ INITIATE message. 

wotatus Low-order word of lParam, if replying to 
WM. DDE_ EXECUTE message. 

hCommands High-order word of |Param, if replying to 
WM_ DDE. EXECUTE message. 
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wstatus Low-order word of |Param, if replying to any other 
message. 

altem High-order word of lParam, if replying to any other 
message. 


When replying to a WM_ DDE_INITIATE message, the [Param parameter 
contains aApplication, an atom that specifies the name of the replying 
application, and aTopic, an atom that specifies which topic the replying 
server window is associated with. 


When replying to a WM_ DDE. EXECUTE message, the |Param parame- 
ter contains wStatus, a word that specifies information in response to the 
received message (as detailed in the following list), and hCommands, a 
handle to the data item that specifies the string of commands. 


When replying to all other messages, the [Param parameter contains — 
wStatus, and altem, an atom that specifies which data item is involved. 


The word wstatus contains the following information: 


Bit/Name Meaning | 


15/fAck 1=Request accepted. 
O=Request not accepted. 
14/fBusy 1=Busy. 
O=Not Busy. 
13-8 /- Reserved for Microsoft use. 
7-0/- Reserved for application-specific return codes. 


An application is expected to set fBusy if it is unable to respond to the 
request at the time it is received. The fBusy flag is defined only when fAck 
is ZeTO. | 


WM_ DDE_ REQUEST 


This message is sent from client to server to request that the server pro- 
vide a data item to the client. 


The receiving application is expected to respond with a WM_ DDE_ DATA 


message containing the requested data, if possible; otherwise, it is 
expected to respond with a negative WM. DDE_ ACK message. 
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Parameter Description 

cfFormat Low-order word of |Param. A registered clipboard format 
number. : | 

altem High-order word of 1Param. An atom that specifies which 


data item is being requested. 


WM_ DDE_ DATA 


This message is sent by a server to notify a client of the availability of 
data. 


Parameter Description 


hData Low-order word of |Param. A handle that specifies the 
global memory object containing the data. 


altem High-order word of [Param. An atom that identifies the 
available data item. 


The global memory object identified by hData contains the following: 


Word/Name Content : | 


1/fAck <4 If bit 15 is 1, the receiving (client) application is expected 
bi to send a WM_DDE_ ACK message after the memory 
object has been processed. If bit 15 is 0, the client appli- 
cation should not send an ACK message. 


Oe a = i 
-/- f £2218 Bit 14 is reserved. 


~/fRelease If bit 13 is 1, the client application is expected aoe 
certain conditions) to free the memory object alter pro- 
cessing it. If bit 13 is 0, the client application should not 
free the object. For a more complete discussion, see 


Pe ae Chapter 9, “Windows DDE: Rules of the Road.” 


—/ fResponse If bit 12 is 1, this data is offered in response to a 
WM_ DDE_ REQUEST message. [f bit 12 is 0, this data 
is offered in response to a WM_DDE_ ADVISE message. 


—/- Bits 11-0 are reserved. 
2/cfFormat Registered clipboard data format number. 
3—n/Data This is the data. It is in the cfFormat format. 
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WM_DDE_ ADVISE 


This message (sent by a client application) requests the receiving applica- 
tion to supply an update for a data item whenever it changes. 


The receiving application is expected to reply with a positive . — 
WM_ DDE_ ACK message if it can provide the requested data, or with a : 
negative one if it cannot. 


Parameter Description 


hOptions Low-order word of |Param. A handle that identifies a glo- 
bal memory object. 


altem High-order word of IParam. An atom that specifies the 
data item being requested. 


The global memory object identified by hOptions contains the following: 


Word /N ame Content 


1/fAck 26, If bit 15 is 1, the receiving ae application is 

= requested to send its WM_ DDE_ DATA messages with 
the ACK-requested bit (fAck) set. This offers a flow- 
control technique whereby the client application can 
avoid overload from incoming DATA messages. 


x L Fy 
ot f iad & 
i Pos F pom fiP 
Deve Yoel 


—-/fNoData If bit 14 is 1, the server is requested to send its 

WM_ DDE_ DATA messages with a null hData handle. 

ees These messages are alarms telling the client that the 

bE COLE source data has changed. Upon receiving one of these 
alarms, the client can choose to call for the latest version 
of the data by issuing a WM. DDE_ REQUEST message, 
or it can choose to ignore the alarm altogether. This 
would typically be used when there is a substantial 
resource cost associated with rendering and/or assimilat- 
ing the data. 


—/- Bits 13-0 are reserved. 


2/cfFormat The client’s preferred type of data. Must be a registered 
clipboard data format number. 


WM_~ DDE_ UNADVISE 


This message is sent by a client application to a server application to indi- 
cate that the specified item should no longer be updated. 
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The server is expected to reply with a positive WM_DDE_ ACK message if 
it can honor the request, or a negative one if it cannot. 


Parameter Description 


altem High-order word of |Param. An atom that specifies which 
data-update request is being retracted. If a null atom is 
provided, the meaning is to retract all active 
a DDE ADVISE conversations associated with the 
chent. 


The low-order word of !|Param is reserved. 


WWM_ DDE- POKE 
This message requests an application to accept an unsolicited data item. 


The receiving application 1s expected to reply with a positive 
WM_ DDE_ ACK message if it accepts the POKE data, or with a negative 
ACK message if it does not. 


Parameter Description 

hData Low-order word of |Param. A handle that specifies the 
global memory object containing the data. 

altem High-order word of [Param. An atom that identifies the 
data item to the receiving application. 


The global memory object identified by hData contains the following: 


Word/Name Content 
1/- Bits 15-14 are reserved. 


—/fRelease If bit 13 is 1, the receiving application is expected (under 
certain conditions) to free the memory object after pro- 
cessing it. If bit 13 is 0, the receiving application should 
not free the object. For a more complete discussion, see 


Chapter 9, “Window DDE: Rules of the Road.” 


—/- Bits 12-0 are reserved. 
2/cfFormat Registered clipboard data format number. 
3—n/Data This is the data. It is in the cfFormat format. 
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WM_DDE_ EXECUTE 


This message sends a string to a server application to be processed as a 
series of commands. The server application is expected to post a 


WM_ DDE_ ACK message in response. 


Parameter 


hCommands 


Description 


High-order word of IParam. A handle that identifies a 
global memory object containing the copa ads) to be 
executed. For details, see Chapter 9, “Windows DDE: 
Rules of The Road.” 


The low-order word of |Param is reserved. 


10.3. Additional Clipboard Formats 


The second component in the DDE protocol is a set of new clipboard data 
formats. There are several clipboard data formats already available, 
including CF_ TEXT, CF_ BITMAP, CF. SYLK, CF_ METAFILEPICT, 
CF_ DIF, and so forth. The new formats are described as follows: 


Format 


CF_RTF 
CF_ WK1 
CF_ BIFF 
CF_ CSV 
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Description 


Rich-text format. 
Lotus 1-2-3 file format. 
Microsoft Excel format. 


Comma-separated variable format. 
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11.1 Introduction 


The WinOldAp Dynamic Data Exchange (DDE) interface allows a Micro- 
soft Windows application, called a “shell,” to manipulate an old DOS pro- 
gram in the same manner as a user would under Windows. Furthermore, 
the interface contains useful features such as downloadable macros and 
menus. These features enable the shell to encapsulate the old application, 
allowing the user to access the application only through the shell. Both 
level 1 and 2 DOS applications will work with shells. A shell can control 
more than one WinOldAp instance, but a WinOldAp instance can be con- 
trolled by only one shell at a time. 


The interface’s primary goal is to provide enough functionality, flexibility, 
and simplicity to warrant the writing of shells. Simplicity in this case 
means simplicity in the shell program. Functionality and flexibility mean 
giving the shell writer enough. power to write a useful shell. The protocol 
has a somewhat conflicting secondary goal: to be extensible to allow for 
additional features that cannot be included in the first release because of 
schedule constraints. Finally, the interface tries to be consistent between 
different application levels. 


11.2 A Sample Session 


In the typical case, the shells will be active before the old application is 
invoked, so WinOldAp must notify each shell of its presence. It does so by 
starting an “identify” conversation with the old application name as the 
topic. In the identify conversation the shell and WinOldAp exchange infor- 
mation about each other. 


In the identify conversation, the initiating WinOldAp is in control, con- 
trary to the natural order, in which the shell should be in control. Once 
the shell and WinOldAp establish each other’s identity, the shell can take 
control of the conversation by exchanging roles with WinOldAp; WinOl- 
dAp becomes the passive server and the shell becomes the active client. 
The exchange takes place when WinOldAp terminates the identify conver- 
sation and the shell initiates a new control conversation. 


Once the control conversation is established, the shell can send WinOldAp 
macros and menu items by using the WM_ DDE_ POKE message. Usually, 
these exchanges are done when the conversation is first established, 
although they can be done any time during the conversation—within cer- 
tain limitations. The shell can also request information from WinOldAp, 
such as application data, current menu items, and current macros. Finally, 
the application can request to be advised when certain user actions are 
performed, such as changes in the old application state and use of macros. 
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When the shell is ready to start the application, it issues a WM_ DDE_- 
EXECUTE message, which tells WinOldAp to continue running the old 
application. The EXECUTE message can also contain a command macro 
that will be executed before the user gets control of the old application. 


As an example dialog, the diagram below outlines the messages sent when 
a shell adds two macros to a WinOldAp menu before the application is 
executed. The ACK messages are not shown and should be implied. 


shell WinOldAp 
<--- INITIATE ("AppName") Sa259 ; Establish identities 
<--- REQUEST ("“ShellInfo") ----~ 
---- DATA ("ShellInfo") ------ > 


<--- POKE ("WinOldApinfo") ---- 
<--- TERMINATE ---------------~ 


---- INITIATE ("“AppName") ----> ; Establish conversation 
---- POKE ("Macro", Macrol ) -> ; Add menu macros 
---- POKE ("Macro", Macro2 ) -> 


-~--- POKE ("Menu", Menul ) ---> ; Add menu items 

---- POKE ("Menu", Menu2 ) ---> 

---- ADVISE ("OldApState") ---> ; Advise when application is ready 
esos EXECUIE: ()i Se ecseesee=—5= > ; Start the old application 

<--- DATA ("OldApState") ----- ; User context switches 

Kso= TERMINATE Sen e esate rere ; Old app requests termination 
eoa= > TERMINATE. =-SSeneeres2n= > ; Old app terminates 


11.3 Full DDE Compliance 


This protocol intends to comply fully with the DDE standard. In this way, 
any enhancements to the DDE protocol, such as extensions for networks, 
will be included. Among other requirements, compliance requires using all 
the DDE fields in their intended manner, adopting the EXECUTE com- 


mand syntax for macros, and using the proper message functions. 


11.4 Naming 


Each data object, event, and action has a unique name. Objects are 
accessed by using atoms formed from their names. Predefined objects can 
have alphabetic names (such as WindowInfo) or integer names (such as 

$f 1024), Objects created for a shell have integer names that correspond to 
their identification number. Identification numbers of objects are returned 
in the acknowledgement message of their creation operation. For simpli- 
city, names are not overloaded. That is, the same name does not refer to 
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different objects depending on the operation. The currently recognized 
names are as follows: 


Name Description 

MenuList List of current menu items 
Menu The menu manager 

#2048 to #3071 Individual menu items 
MacroList. List of current macros 

Macro The macro librarian 

#1024 to #2047 Individual macros 

WindowlInfo The state of the old application window 
WinOldApInfo WinOldAp information 
ShellInfo Shell information 

OldApState The state of the old application 


11.5 Sequential Shells 


To prevent control conflicts, a WinOldAp instance can be controlled by 
only one shell at a time. However, under certain situations, it may be 
desirable for several shells to have data objects present in a given Win- 
OldAp instance. To accommodate this, the protocol includes a sequential 
shell concept in which WinOldAp deterministically gives a sequence of 
“temporary” shells control before it gives control to a final “permanent” 
shell. Temporary shells perform their WinOldAp operations and terminate 
the control conversation before activating the old application with an 
EXECUTE message. WinOldAp gives control to temporary shells in the 
following sequence: 


Type Description 

General The shell used for several applications. 
Specific. The shell with application-specific knowledge. 
Execing The shell that invoked the old application. 


If more than one permanent shell requests final control, WinOldAp assigns 
priority to the shells in the following order: Execing, Specific, and General. 
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If more than one shell of a given type wants permanent control, a pseudo- 
random selection is made. 


To determine a shell’s type, WinOldAp uses the SHELLINFO data struc- 
ture passed during the identify conversation. If the shell executes an old 
application, the hChild field should contain the AX register value 
returned by the Exec function. WinOldAp uses this field to identify which 
parent application gets the highest priority. 


11.6 WinOldAp States and Actions 


The old application may be in three states: StartUp, Active, and InActive. 


The StartUp state is entered immediately after the WinOldAp is started 
but before the old application is executed. The StartUp state allows the 
shell to perform actions such as adding menu items before the application 
has started. It is left when no shell wants control of the old application or 


when a shell posts a WM_ DDE_ EXECUTE message. 


After the old application leaves the StartUp state, it enters the Active 
state where the old application is running. In the Active state, the old 
application has input focus, allowing the user to use the application in the 
normal manner. 


The Active state is left for the InActive state when the user presses 
ALT+ESC or ALT+TAB or when a [Switch] macro code is executed. In the 
InActive state, the old application no longer has keyboard focus. The 
InActive state is left for the Active state when the user context switches to 
the old application or a WM. DDE. EXECUTE message is received by the 
old application window. A bUserLock flag in the OldApState data struc- 
ture can be set to prevent the user from moving an application from the 
InActive to the Active state. 


The DDE conversation can be in five states: before an identify conversa- 
tion, during an identify conversation, after an identify conversation and 
before a control conversation, during a control conversation with no 
advisories set, and during a control conversation with advisories set. All 
conversations are terminated when the old application exits. 


A change in the DDE conversation state does not affect the old application 


state except for the EXECUTE and the INITIATE messages. 
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11.7 Notification Events 


Notification messages are sent when an event occurs for which the shell 
has requested advice. Currently, the shell can request notification only on 
changes in OldApState caused by the user and by execution of macros. 
Notification events do not change the old application state. 


11.8 DDE Messages 


The two kinds of conversations established between the shell and Win- 
OldAp—the identify and control conversations—have different sets of mes- 
sages that are valid. All the messages in the conversations follow the DDE 
rules outlined in Chapter 9, “Windows DDE: Rules of the Road.” 


11.8.1 Messages in the Identify Conversation 


WM_DDE_INITIATE 


This message is sent by WinOldAp to notify shells that a particular old 
application has been invoked. 


Parameter Description 


wDDEserverID An atom containing “Shell”. 
WDDETopicID An atom containing the name of the application. 


Response 


If a shell exists that wants to control WinOldAp, it should acknowledge. 
Once the conversation has been established, WinOldAp sends a POKE 
message with the application’s information. If no shell acknowledges, then 
WinOldAp continues execution in a normal manner (see Section 11.6, 
“WinOldAp States and Actions,” for more details). 
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WM_DDE_REQUEST 


This message is sent by WinOldAp to request the shell characteristics for 
sequencing and conflict resolution. If only one shell wants control of 
WinOldAp, this message may not be sent. 


Parameters Description 

wDatalD The atom named “ShellInfo”. 
wFormat The binary clipboard format. 
Response 


The shell sends a WM_ DDE_ DATA_ MESSAGE containing a 
SHELLINFO data structure. See Section 11.12, “Shell Information,” for 
more details. If a shell does not have a SHELLINFO data structure, it 
sends a negative acknowledgement. WinOldAp will assume the shell is a 
permanent general type. 


WM. DDE_ DATA 


This message is sent by the shell to respond to a request for shell informa- 
tion. 


Parameter Description 
wDDEID The atom named “ShellInfo”. 
hDDEData A SHELLINFO data structure, explained in 


Section 11.12, “Shell Information.” The flags 
fACKRequired and fChientRelease may be set 
according to the shell’s request. The wFormat 
parameter must be in the binary clipboard 
format. 


Response 


WinOldAp will acknowledge if the fACKRequired flag is set. 


WM_ DDE... POKE 
This message sent is by WinOldAp to send a command string to the shell. 


This information might be necessary for some servers to determine 
whether they should continue with the DDE session. 
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Parameter Description 
wDatalD An atom containing “WinOldApInfo.” 
hDDEData The WOAINFO data structure with fACK- 


Required set and fServerRelease cleared. The 
wFormat parameter will be binary. 


Response 
A positive acknowledgement by the shell commits it to initiating a control 


conversation. If no shell commits, WinOldAp will execute the application 
in a normal manner. 


WM~- DDE_ TERMINATE 


This message is sent by WinOldAp (normal) or the shell (abort) to ter- 
minate the identify conversation. 


Parameter 


None 


Response 
The shell does not respond to a normal termination message. 
Since termination is a part of the normal conversation sequence, 


WinOldAp ignores the abort termination message, except that it does not 
expect a control conversation to be initiated by the shell. 


WM... DDE_ ACK 
This message is sent by the shell to acknowledge the INITIATE and POKE 


messages. 


Parameter Description 

wDDETopic Used to identify the applicaton. 
wDDEServer Used in response to initiates. 
wotatus Used in response to poke. 
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11.8.2 Messages in the Control Conversation 


WM_ DDE_ INITIATE 


This message is sent by the shell to establish a control conversation 
between the shell and WinOldAp. 


Parameter Description 

DDEServerID An atom containing “WinOldAp”. 

DDETopicID An atom containing the name of the application. 
Response 


WinOldAp will send a positive acknowledgement if the shell is meant to 
control this WinOldAp instance during this identify-control cycle. 


WML_ DDE_ TERMINATE 


This message is sent by the shell (normal) or WinOldAp (abort) to ter- 
minate the control conversation. 


Parameter 
None 
Response 


Terminating the conversation does not remove any data items that may 
have been added during the conversation. 


WM_ DDE. POKE 


This message is sent by the shell to add, change, or delete a data item in 


WinOldAp. 
Parameter Description 


wDatatlId Valid wDatald values are as follows: 
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hDDEData 
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Value Name/ Description 


Macro The macro librarian. 
Menu The menu manager. 
OldApState The UserLock flag. 
Windowlnfo The application window 
information. 


Contains the actual information. A POKE of an 
OldApState structure will affect only the User- 
Lock flag of the application’s structure. See Sec- 
tion 11.13, “Macro Support,” and Chapter 12, 
“Old Application Menu Support.” 


WinOldAp will send a positive or negative acknowledgement depending on 
the success of the POKE operation. See the WM_ DDE ACK description 
that follows for error codes. 


WM_ DDE_ REQUEST 


This message is sent by the shell to find information on the current state 
of WinOldAp. The wDataID parameter identifies a WinOldAp data item. 
The following are valid atoms: 


Name 


MenuList 

#2048 to #3071 
MacroList 
#1024 to #2047 
WinOldApInfo 
WindowlInfo 
OldApState 


Description 


List of current menu items. 
Individual menu items. 

List of current macros. 

Individual macros, 

WinOldAp information. 

The application window information. 


The current OldApState. 


All objects should be requested in the binary format. 


For more information, see the appropriate section. 
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Response 


If wDataID and wFormat are valid, WinOldAp will send a 
WM. DDE_ DATA message with fACKRequired cleared and fClient- 
Release set. A negative WM_ DDE_ ACK is sent otherwise. 


WM_ DDE_ ADVISE 


This message is sent by the shell to set up notification about some user 
action in WinOldAp. The wDDEID atom is associated with a user event. 
The following objects are recognized: 


Name Description 


OldApState This structure contains a LastUserAction field 
that changes every time the user does a context 
switch. A notification is sent when this field 
changes. 


#1024 to #2047 A notification will be sent after the specified 
macro is executed. 


The hOption parameter has the following structure: 


Word/Name Contents 


1/fACKRequired If bit 15 is set, the shell wants an acknow- 
ledgement of the request. 
~/fNoData If bit 14 is set, the shell just wants alarms 


(data messages with no data). If bit 14 is 
cleared, WinOldAp sends data messages that 
have just a data header. The data header 
will have f[ACKRequired cleared, fClien- 
tRelease set, and a binary clipboard format. 
Typically, the shell programmer will have 
this bit set. 


2 /wFormat The binary clipboard format. 


As a convenience to the programmer, hOption can be NULL. This will be 
interpreted to mean f[ACKRequired cleared and fNoData set. 
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Response 


If fACKRequired is set, a WM. DDE_ ACK message will be sent, indicat- 
ing the success of the advise request. If the advise is successful, 
WM_DDE_- DATA messages are sent as notification when the advise 
event occurs. 


WM_ DDE_ UNADVISE 
This message is sent by the shell to disable WinOldAp notifications. 


Parameter Description 


wDDEID An atom associated with a user event. See 


WM_ DDE_ ADVISE for a list of valid events. 


Response 


A WM_ DDE. ACK message is sent indicating the validity of the wODEID. 


WML_ DDE_ DATA 


This message is sent by WinOldAp in response to a request or a user event. 
Parameter Description 
wDDEID An advise or a request atom. For a list of valid 
atoms, see the WM_ DDE_ ADVISE and 
WM_ DDE” REQUEST messages. 
To minimize the work required of the shell programmer, the f[ACKRe- 
quired flag of the hDDEData object will be cleared and the fClientRelease 
flags will be set. The hDDEData parameter may also be NULL if the shell 


requests an alarm notification. 


Response 


None 


WM_ DDE_ EXECUTE 


This message is sent by the shell to place the old application in an active 
status and execute the passed commands. 
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Parameter Description 


hCommands If hCommands is NULL, no commands are executed, but 
the old application is still placed in an Active state. Any 
passed command is executed before the user gets control. 
The EXECUTE message follows the syntax laid out in 
Chapter 10, “Windows DDE: Protocol Definition,” and 
Section 11.14, “Command Language.” 


Response 


A positive acknowledgement is sent if any part of the command could be 
executed. 


WM_ DDE_ ACK 


This message is sent by WinOldAp to acknowledge an ADVISE, UNAD- 
VISE, POKE, or EXECUTE message. 


Parameter Description 

wstatus Bit 15 indicates the success of the operation. If a 
REQUEST or a POKE message is successful, bits 14-0 
contain the object identification number. If the operation 
is unsuccessful, bits 14-0 contain an error code. 


The error code has the following names: 


Error Name 

i Invalid object 

2 Invalid format 

3 Invalid fRelease flag 
4 Invalid fNoData flag 
5 Invalid fAckReq flag 
6 Invalid syntax 

10 Unable to perform operation 
11 Invalid operation 

12 Out of memory 

13 Invalid parameters 
14 Invalid flags 


148 


rr 


Old Application DDE Interface 


11.9 Window Information 


Window infomation can be requested by sending a WM_ DDE_ REQUEST 
message with an atom named “Windowlnfo.” It can also be changed by 
sending a WM_ DDE~ POKE message. 


Word / Name Contents 


1 /fACKRequired Always cleared. Bit 14 is reserved. 
~/fChentRelease Always set. Bits 12-0 are reserved. 
2/wFormat The binary Clipboard format. 
3/fVisible 0=No change. 


1=Hide the old application window. 
2=Show the old application window. 


4/hIcon 0=No change. 
1—Use the default three letter icon. 


Other=An icon that can be used by the old appli- 
cation. 


5-6 /(Reserved) Must be zero. 


11.10 WinOldAp Information 


The shell can request information about the old application by sending a 
WM_ DDE_ REQUEST message with an atom named WinOldAplnfo. 
WinOldAp will respond with a WOAINFO data structure. The same 


data structure is poked to the shell during the identify conversation. 


Word/N ame Contents 


1/fACKRequired Set when poked during the identify conversation. 
Cleared when requested during the control conversa- 
tion. 


-/- Bit 14 is reserved. 


-/fClientRelease Cleared when poked during the identify conversation. 
Set when requested during the control conversation. 


—/- Bits 12-0 are reserved. 


2/wFormat The binary clipboard format. 
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3/numReq The number of shells that requested control during the 
last identify conversation. 

4/numGranted The number of shells that have been granted control. 

5 /numOther The number of other instances of this application at 


the time this application was started. This number 
corresponds to the number of tick marks found in the 
default application icon. 


6/pifBehavior The pifBehavior word from the application’s PIF file. 


7 /hTask The task handle of the old application instance. This 
field will match the AX register value returned by the 
Exec function after loading the application. 


8-9/(Reserved) | Must be zero. 


10—n/szCommandLine 
The command line passed to the application when the 
application was started. 


11.11 The Old Application State 


Information about the old application state can be requested by the shell 
by sending a WM_ DDE_ REQUEST message with an atom named 
“OldApState”. WinOldAp responds with a STATE data structure, which 
contains the following. 


Word/Name Contents 


1/fACKRequired Always cleared. 

—/- Bit 14 is reserved. 
—/fClientRelease Always set. 

~/- Bits 12-0 are reserved. 
2/wFormat The binary clipboard format. 
3/OAState O=Old application not started. 


1=Old application running. 
2=Old application terminated. 


4/LastUserAction O=User started the application. 
1=User switched into the application. 
2=User switched out of the application. 
3=User terminated the application. 


5 /UserLock The user lock is set if this field is nonzero. 
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11.12 Shell Information 


The shell-information data structure is sent by the shell during the iden- 
tify conversation to determine the sequencing order of the shells. The 
SHELLINFO structure characterizes the future behavior of the shell. It 


contains the following: 


Word / Name Contents 


1/fACKRequired Set if the shell wants WinOldAp to acknowledge. 

-—/- Bit 14 is reserved. 

—/fClientRelease Set if the shell wants WinOldAp to release the 
SHELLINFO data structure. 

—/- Bits 12-0 are reserved. 

2/wFormat The binary clipboard format. 

3/hChild If the shell starts an old application, this field 
should be set with the AX register value returned 
by the Exec function. Otherwise, it can be set to 
Zero. 

4/Bits Bits 15-10 reserved. 

—/fRequest | Bit 9. Set if the shell requests information. 

—/fAdd Bit 8. Set if the shell adds data items. 

—/fPredefine Bit 7. Set if the shell modifies a data object that 
the shell did not add. 

~—/fAdvise Bit 6. Set if the shell sets advisories. 

—/fExecute Bit 5. Set if the shell uses the EXECUTE 
message. 

—/fTemporary Bit 4. Set if the shell terminates immediately. 

-~/f{NoTemps Bit 3. Set if the shell does not want any tem- 


porary shells to be given control before it is. This 
field is valid only if hChild matches the 
application’s task handle. 


af Bit 2 is reserved. 


—/type Bits 0-1. If 0, this is a general shell that works 
with several different applications. If 1, this shell 
is designed for a specific old application. 


5/wMacroSize The total size in bytes of the MACRO data 
structures downloaded by the shell. WinOldAp 
will use this field to determine the size of the 
macro buffer used to store any downloaded 
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6 /wMenuSize 


7 /Reserved 


macros. Setting this field does not guarantee that 
the specified size will be allocated. Shells should 
still use acknowledgement messages to certify the 
success of the downloading operation. 


The total size in bytes of the MENU data struc- 
tures downloaded by the shell. WinOldAp will use 
this field to determine the size of the menu buffer 
used to store any downloaded menu items. Set- 
ting this field does not guarantee that the speci- 
fied size will be allocated. Shells should still use 
acknowledgement messages to certify the success 
of the downloading operation. 


Must be zero. 


11.13 Macro Support 


Macros uses the DDE execute command syntax and semantics. See Section 
11.14 “Command Language,” for details. WinOldAp starts with a set of 
predefined macros in their default settings. The shell has the ability to add 
new macros, delete old macros, and change existing macros. The 
predefined macros are as follows: 


Name ID# 
Mark 1024 
Copy 1025 
Paste 1026 
Scroll 1027 
Switch 1028 
Close 1029 
Null 1030 
RedrawsScreen 1031 
PasteHOL 1032 
PasteSpace 1033 


Default Description 


"|Mark]" Default system-menu items 
"|Copy|" Default system-menu items 
"{Paste|” Default system-menu items 
"{Scroll}" Default system-menu items 
"(Switch]" Default system-menu items 
"{Close]" Default system-menu items 
"/Close]" Default system-menu items 
"|Close]" Redraw the screen 


"{Enter}" Paste operation 
"{Enter}" Paste operation 


Each macro has a unique identification number between 1024 and 2047. 
This number can be used with the MAKEINTATOM C macro to form 


an atom name that refers to the macro. 
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Macros are manipulated using WM DDE_ POKE messages. The wDDEID 


parameter contains an atom whose name is the macro ID. The hData 
parameter refers to the MACRO data structure. 


Word /Name Contents 


1/fACKRequired If bit 15 is 1, WinOldAp will send a 
WM_ DDE... ACK message. 

—/- Bit 14 is reserved. 

—/fServerRelease If bit 13 is 1, WinOldAp will free the global data 
object. 

—/- Bits 12-0 are reserved. 

2/wFormat The binary clipboard format. 

3 /wMacroID The identification number of the macro the 


operation is referring to. If an add action is being 
performed, this field is ignored. 


A/wAction If this field is 0, add the provided macro. If it is 1, 
replace the indicated macro with the provided 
macro. If it is 2, delete the indicated macro. 


5—n/szMacro The macro in the WM_ DDE_ EXECUTE format 
that is a null-terminated ANSI string. If a delete 
action is being performed, this field is ignored. 


If the POKE message is successful and fACKRequired is set, a 

WM_ DDE_ ACK message will be sent with the wODEID containing a 
macro identification atom and bit 15 of wStatus set. Bits 14-0 will contain 
the macro ID. 


If the POKE message is unsuccessful and fACK Required is set, a 

WM_ DDE_ ACK message will be sent with the wODEID containing a 
macro identification atom and bit 15 of wStatus cleared. Bits 14-0 will 
contain an error code that follows the convention set forth Section 11.3, 


“DDE Messages.” 


The shell can request the contents of an individual macro by sending a 
WM_ DDE_ REQUEST message with wDDEID containing a macro 
identification atom. WinOldAp responds with a WM_DDE_ DATA mes- 
sage containing a MACRO data structure with fACKRequired cleared 
and fClientRelease set. 


The shell can also request a list of the currently defined macros by request- 


ing the “MacroList” object. The data message that replies to this request 
contains a handle to the following MACROLIST data structure: 
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Word/Name Contents 


1/fACKRequired Always cleared. 

—/- Bit 14 is reserved. 

—/fClientRelease Always set. 

—/- Bits 12-0 are reserved. 

2/wFormat The binary clipboard format. 

3 /numberMacros Size of the passed macro list. 

4—n/macrolds An ascending list of the identification numbers 


for the currently defined macros. 


11.14 Command Language 


An extension to the concept of keyboard macros, the WinOldAp Macro 
Command Language provides a programmable way to perform operations 
normally associated with the system menu. 


11.15 Command Set 


ABORT switch 
The ABORT command specifies the user’s ability to stop the execution of 


a macro by using a keystroke (such as CTRL+BREAK). The ABORT com- 
mand takes the following parameters: 


Parameter Description 


switch If this parameter is set to ON, enable user aborting of 
macro. If it is OFF, disable user aborting of macro. 


COPY 


The COPY command takes the currently marked area on the screen and 
copies 1t into the Windows Clipboard. 
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MACRO macro-id 


The MACRO command will begin the execution of the specified macro. 
This will allow chaining macros together into one large macro. Recursive 
calls to the same macro will not be supported. 


Parameter Description 


macro-id Specifies the macro associated with this menu change. It 
must be specified and must be an integer corresponding 
to a valid macro. 


MARK option 


The MARK command designates a portion of the screen to be copied into 
the Clipboard. The display may be in either text or graphics mode. The 
MARK command will take the following parameters. If no parameters are 
given, the system is put into the interactive mark mode. The option 
parameter can be one of the following: 


Parameter Description 


SCREEN Marks entire display. 


X, Y, Xext, Yext 
Marks rectangular area of display. The coordinates (X, 
Y) specify the upper-left corner of the rectangle; Xext 
and Yext specify the relative extents. These coordinates 
refer to the current video mode the system is in. Only 
text mode is supported currently. 


MENU menu-id,menu-flags,macro-td 
The MENU command is used to modify the menus. 


Parameter Description 
menu-id Specifies the menu item. 
menu-flags Specifies the changes to be performed. Supported flags 


are: MP_ GRAYED, MF_ ENABLED, MF_ DISABLED, 
MF_ CHECKED, and MF. UNCHECKED. Combinations 
of flags may be set using the OR operator. 


macro-id Specifies the macro to be associated with this menu 
change. 
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NULL count 


The NULL command is used to specify the number of times an applica- 
tion will unsuccessfully attempt to read the keyboard before control 
returns to the macro executive. This allows macro programmers to control 
the behavior of a particular application. 


Parameter Description 
count Specifies the number of times to fail, between 1 and 255. 
PASTE 


The PASTE command takes the text contents of the clipboard and 
directs it to the application. The PASTE command takes no parameters. 


Note 


Characters for level 2 applications are always converted to the OEM 
character set. 


SCROLL 

The SCROLL command enables the standard Windows scroll mode. In this 
mode, the user may use the keyboard arrow keys to scroll the application. 
This command 1s valid only for level 1 applications. 


The SCROLL command takes no parameters. 


SWITCH 
The SWITCH command performs a context switch from an application. 


This would be the equivalent of the user pressing ALT+TAB. At this point, 
any remaining macro commands will be ignored. 
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11.16 Syntax of Macro Commands 


The WinOldAp Macro command language follows the syntax of the 
WM_ DDE_ EXECUTE message. Chapter 9, “Windows DDE: Rules of the 


Road,” presents the syntax for valid commands. This syntax explicitly 


allows applications to extend this definition to support their own 


applcation-specific operation codes. It is through this type of extension 


that the WinOldAp macro command language has been defined. The 
resulting syntax is listed below. 


<execute string> 
<token> 
<keystroke> 


<modifier> 
<shift> 
<control> 
<alt> 
<character> 


<letter> 
<digit> 


<symbol> 


<quoted character> 
<escape character> 
<key equivalent> 
<keyword> 


<function key> 


<number> 
<app opcode> 
<WOA opcode string> 


<abort switch> 
<macro id> 
<mark option> 
<menu id> 
<menu style> 
<menu flag> 


howd 


ae 62 #8 +e we 


= <menu flag>["!"<menu style>] 


[<token>]<execute string> 
<keystroke> | <app opcode> 
[<modifier>]<character> ! 
[<modifier>]<key equivalent> 
[<shift>] [<control>] [<alt>] 
+ 


~ 


~~ 


>=SCREEN |! <number>, <number>, <number>, <number> 


<number> 


MF_GRAYED | MF_ENABLED | MF_DISABLED | 
MF_CHECKED | MF_UNCHECKED 


<letter> | <digit> | <symbol> |! 
<quoted character> 

a= eA) cee Ee fod 

SSO 1} 2437 47576174 8 1-9 1 

= 1 @ Pe si Zi eset Ci) | 
Se oe ee ee 
tf? : tt : . . ' | 1 tet |j ) fy | 

| $1 ¢ * | | ier | 1° 4 | / 
>= <escape characterl><escape character1> 

gS ee de ae oe 

:= {<keyword>} 

:= TAB | ESC | ENTER | HOME |} END ! LEFT }{ RIGHT } 
UP | DOWN | PGUP |! PGDN | NUM ! SCROLL !} SYS ! 
PRTSC | BREAK | <function key> | NULL 

=Fl1{|F2)}F3 {| F4! FS } F6 | F7 | FB! FO } 
F1O | Fil {| Fl12 

:= <digit> [<number>] 

:= "["<WOA opcode string>"]" 

:= ABORT<abort switch> | COPY | 

MACRO<macro id> | MARK{<mark param>] |! 
MENU<menu id>,<menu style>,<macro id> | 
NULL <number> |! PASTE ! SWITCH | SCROLL 
:= ON | OFF 
>= <number> 
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12.1 Introduction 


The DDE extensions in WinOldAp will allow a shell program to download 
menu information to WinOldAp. This information can be used to create, 
delete or modify menus and menu items in a level 1 or level 2 application. 
The user interface for level 2 applications is designed to match that of 
level 1 applications as closely as possible. The DDE messages sent to 
modify menus are modeled closely after the user functions used for Micro- 
soft Windows applications. 


WinOldAp will have predefined menu items in the control menu. For level 
2 applications, the standard control-menu items will exist with limited 
functionality. Both level 1 and 2 applications will have Mark, Copy, Paste, 
and Scroll (Scroll being grayed in level 2 applications) items appended to 
the bottom of the menu. These items should not be modified by the shell 
programs since unpredictable results may occur. The standard items in the 
control menu for level 1 applications may not be modified. 


The predefined menu items are as follows: 


Name/ID MacrolID /Default Style 


System Menu/2048 NULL/MF_ POPUP 


Separator/2049 NULL/MF_ SEPARATOR 
Mark /2050 1024/MF_ ENABLED 
Copy/2051 1025/MF_ GRAYED + 
Paste /2052 1026/MF_ GRAYED « 
Scroll /2053 1027/MF_ ENABLED # 
Restore /2054 1030/MF_ GRAYED & 
Move/2055 1030/MF_ GRAYED & 
Size /2056 1030/MF_ GRAYED & 
Minimize /2057 1028/MF_ENABLED & 
Maximize /2058 1030/MF_ GRAYED & 
Separator /2059 NULL/MF_ SEPARATOR 
Close /2060 1029/MF_ GRAYED 


An asterisk (+) indicates that WinOldAp sets the MenuStyle for these 
according to the current state of the Menu Control Panel. If there is not 
an area currently marked on the screen, the copy item is automatically 
grayed. If there is no data in Clipboard in the CF_ TEXT clipboard for- 
mat, the Paste item is grayed. WinOldAp handles these states directly. 
For this reason, these items should not be modified. 
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A pound sign (#) means that this item is only enabled in level 1 applica- 
tions. It has no function in level 2 applications. 


An ampersand (&) indicates that these items are referenced only by these 
ID’s in level 2 applications. Level 1 applications may not access these 
items. The Close option is initially MF_GRAYED but becomes 

MF. ENABLED when the application terminates. Again, these items 
should not be modified. 


Each menu item has a unique identification number between 2048 and 
3071. The menu ID can be used with the MAKEINTATOM C macro to 
form an atom name that refers to the menu. 


Menus are manipulated using WM_ DDE_ POKE messages. The wDDEID 
parameter contains an atom whose name is the menu ID. The DDE hData 
parameter refers to a structure in the following format: 


Word/Name Content 


1/fACKRequired If bit 15 is 1, WinOldAp sends a WM_ DDE_ ACK 
message containing a success or failure flag and 
the menu ID 

~/- Bit 14 is reserved. 

—/fServerRelease If bit 13 is 1, WinOldAp will free the global 
object. 

—/— Bits 12-0 are reserved. 

2/wFormat The binary clipboard format. 

3/wIDChangeltem This item’s value depends on the flags set in the 


wChange parameter that follows. If 

MF... BYPOSITION is selected, this number con- 
tains the physical position within the menu to be 
changed. If MF. BYCOMMAND (default) is 
selected, this item contains the menu ID of the 
item to be changed. This parameter is the same 
as the wIDChangeltem used for the 
ChangeMenu function documented in the 
Microsoft Windows Programmer’s Reference. 
Top-level menu items (menu titles) may only be 
updated by using the MF_ BYPOSITION flag. 


4/wIDNewltem This is a new menu ID. For details, see Section 
12.2, “Pop-up Menus.” 
5/wMenulD This is the menu ID of the pop-up menu to be 


modified. This is only used when modifying menu 
items within a pop-up menu. See Section 12.2, 
“Pop-up Menus.” If a top-level menu item is 
being modified, this item is NULL. 
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6 /wMacro 


7 /wChange 


8-23 /szItem 
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This word is the macro ID that is to be associated 
with this menu item. If the MF_POPUP or 
MF_SEPARATOR flag is used, this item is 
NULL. 


This word is a combination of menu flags. These 
flags are combined using the bitwise OR operator. 
See the Microsoft Windows Programmer’s Refer- 
ence for a more detailed explanation of this 
parameter. Note the flags in the following list 
that are not supported for WinOldAp applica- 
tions. 


This is a null-terminated ASCII string that is no 
longer than 31 characters, including the null ter- 
minator. It the string that will be displayed in the 
menu. This field is ignored if the 

MF... SEPARATOR flag is used. The & character 
is used, as in Windows applications, to preceed 
the character in the string that is to be used as 
the mnemonic character for this item. 


The flags in the wChange field can be combined using the bitwise OR 
operator. The field is a combination of the following flags: 


Flag 
MF... APPEND 


MF. BITMAP 

MF_ BYCOMMAND 
MF_ BYPOSITION 
MF. CHANGE 

MF_ CHECKED 


MF_ DELETE 


MF_ DISABLED 


MF_ ENABLED 


Description 


Append the new item to the end of the menu. The 
wiDChangeltem parameter is not used if this flag 
is set. 


Unsupported. 


The wIDChangeltem parameter gives the menu 
ID of the item to be changed. (Default) 


wlDChangeltem gives the position of the menu 
item to be changed. The first item is located at 
position zero. 


Change or replace ‘the specified item. 


Place a checkmark next to the item. Valid only in 
a pop-up menu. 


Delete the item. The system menu cannot be 
deleted. However, system-menu items available to 
the shell may be deleted. 


Disable the item without changing its appear- 
ance. The item cannot be selected. 


Enable the item to allow it to be selected. 


(Default) 
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MF_ GRAYED Disable and gray the item to show that it cannot 


MF_ INSERT 


be selected. 


Insert a new item just before the specified item. If 
wlDChangeltem is greater than or equal to the 
number of menu items, and the 
MF_ BYPOSITION flag is set, the operation is 
stopped (for example, when inserting a menu 
title, if wIDChangeltem is equalled to and there 
are four or less menu titles on the menu bar, the 
werk will be aborted). MF_APPEND should 
e used. 


MF_ MENUBARBREAK 


Unsupported. 


MF_. MENUBREAK Unsupported. 
MF_ POPUP Creates a pop-up menu with witem containing 


MF_ REMOVE 


the string to be used in the menu bar for the 
pop-up. This can only be used with top-level 
menu items. For more details on the use of this 
flag, see Section 12.2, “Pop-up Menus.” 


Remove the item from the menu but do not delete 
it. The item is not selectable. 


MF_ SEPARATOR Draw a horizontal dividing line. This flag is valid 


only in pop-up menus and cannot be enabled, dis- 
abled, checked, grayed, or highlighted. 


MF_STRING Use a string (wltem) as the menu item. (Default) 
MF_ UNCHECKED Do not place a checkmark next to the item. 


(Default) 


The following rules apply to the flags: 


MF_INSERT, MF_ BYCOMMAND, MF_ ENABLED, 
MF_.UNCHECKED, and MF_ STRING are the default flags. 


The flags MF_ CHANGE, MF_INSERT, MF_ APPEND, 
MF_ REMOVE, and MF_ DELETE should not be used together. 


The MF_ BYPOSITION and MF_ BYCOMMAND flags should not 
be used together. 


The MF_ GRAYED, MF_ DISABLED, MF_ ENABLED, and 
MF... REMOVE flags should not be used together. 


The MF_STRING and MF. POPUP flags should not be used 
together. 


The MF_ CHECKED and MF_ UNCHECKED flags should not be 
used together. 


Old Application Menu Support 


If the POKE message is successful and fACK is set, a WM DDE_ ACK 
message will be sent with the wODEID parameter ontaining a menu 
identification atom and bit 15 of wStatus set. Bits 14-0 will contain the 
menu ID. 


If the POKE message is unsuccessful and [ACK is set, an WM_ DDE. ACK 
message will be sent with the wDDEID containing a macro identification 
atom and bit 15 of wStatus cleared. Bits 14—0 will contain an error code. 


12.2 Pop-up Menus 


The protocol for creating and updating menus for WinOldAp is designed 
to mimic the Windows menu interface as closely as possible while still con- 
forming to the DDE protocol. Pop-up menus are handled slightly 
differently from the Windows interface. To create a pop-up menu, the 
menu title must be created first. This is done by creating a menu item, 
with a menu item ID set in the wIDNewltem parameter, and by using the 
MF. POPUP flag. The wMenuID must be zero when accessing items with 
the MF. POPUP flag set. This is the case since the MF. POPUP flag can 
be used only on top-level (menu-bar) items. The menu ID that you assign 
to this pop-up menu will now be used to insert or append items in the 
pop-up menu. This differs from the way that Windows handles pop-up 
menus in that, here, a pop-up menu is not created in advance and passed 
with the menu title upon creation. 


The following is a high-level example of a pop-up menu: 


1. Create the menu with the following data: 


wIDChangelItem = position if MF_INSERT is used 
wIDNewItem = your menu ID (i.e. 2500) 

wMenulID =O 

wMacro = 0 

wChange = MF_BYPOSITION |! MF_POPUP ! MF_APPEND 
witem = "My Popup Menu" (Null-terminated) 


2. Insert menu items into this menu using: 


wiIDChangeItem = position or another Menu ID in menu 
wIDNewI tem = Menu item ID (i.e. 2501) 
wMenuID = menu ID (2500, in this case) 
wMacro = an existing macro ID 
wChange = MF_INSERT ! MF_BYPOSITION 

(ME_APPEND and MF_BYCOMMAND may be used) 
witem = "My Menu Item" (Null-terminated) 
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12.3 Retrieving Menu Information 


The shell may obtain information about a particular menu item by using 

the WM.. DDE_ REQUEST message with the wDataID paramater specify- jee 
ing the menu ID of the item requested. WinOldAp will send back a a 
WM_ DDE. DATA message that will contain a handle to the same struc- 

ture used by the shell to poke menu commands to WinOldAP. The 

appropriate fields in this structure will be filled with the information 

about the menu item. The wIDChangeltem parameter will contain the 

position of the item in the menu specified by wMenulD. The 

MF... BYPOSITION flag will be set in the wChange parameter to identify 

this. If wMenulID is zero, this item is a top-level (menu-bar) item. The flags 

set in wChange identify the style of the menu. 


The shell can also obtain a list of the currently defined menu items by 


requesting the “MenuList” object. The data message that replies to this 
request contains a handle to a list data structure: 


Word / Name Content 


1/fACKRequired Always cleared. 

~/- Bit 14 reserved. 

—/fClientRelease Always set. 

—/- Bits 12-0 are reserved. 

2/wFormat The binary Clipboard format. 

3 /MenuCount The number of macro ID codes passed back 
including separators. 

4/MenuList This is a list of the menu ID’s available in the fol- 
lowing format: 
MenuList 
MenuList 
where: 


MenuList = Menu Title ID 
Menu Item ID ee 
Menu Item ID 


The MenuList items are in the order that they 
appear from left to right across the screen. There- 
fore, the first MenuList will pertain to the system 
menu. The second MenuList will pertain to the 
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menu in position 0, the third to the menu in posi- 
tion 1, and so on. The system menu list will only 
contain the items specified by WinOldAp. There- 
fore, the standard Windows menu items cannot 
be modified or deleted in level 1 applications. The 
separators (0) are included in the MenuCount 
variable above. 
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13.1 Introduction 


This chapter describes the old application Clipboard-support functions. 
These functions let Microsoft Windows applications copy and paste infor- 
mation with old applications. Access to all old-application Clipboard func- 
tions is through the software interrupt 2FH. The function is placed in the 
AX register as detailed following. The IdentifyWinOldApVersion func- 
tion call must be made first to verify that the functions are present. 


ClipboardCompact 


This function compacts the amount of memory necessary to provide room 
for the requested number of allocated bytes. 


Register Description 
AX Set to 1709H to specify this function 
SI:CX Set to the desired memory size in bytes 


Return Values 


On return, DX:AX contains the number of bytes in the largest block of 
free memory. 


Comments 


WinOldAp is responsible for including the size of any headers in the 
desired memory size, 


CloseClipboard 


This function closes Clipboard. 


Register Description 


AX Set to 1708H to specify this function 
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Return Values 


If there is an error, this function returns register AX equal to zero. 


Empty Clipboard 

This function destroys the contents of Clipboard. 

Register Description 

AX Set to 1702H to specify this function 
Return Values 


If Clipboard was emptied, this function returns register AX not equal to 
ZeTO. 


If it returns AX equal to zero, an error has occurred. 


GetClipboardData 


This function copies data of specified format from Clipboard to a specified 
location. 


Register Description 

AX Set to 1705H to specify this function 

DX Set to the clipboard format supported by 
WinOldAp | 

ES:BX A pointer to the location in which to place the 
data 


Return Values 


If, on return, AX is zero, an error has occurred or data in this format is 
not in Clipboard. 


GetClipboardDataSize 


This function returns the amount of data of specified format contained in 


Clipboard. 
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Register Description 

AX Set to 1704H to specify this function 

DX Set to the clipboard format supported by Win- 
OldAp 


Return Values 
DX:AX contains the size of the data in bytes, including any headers. 


If data in this format is not in Clipboard, DX:AX will contain zero. 


GetDeviceCaps 


This function returns the device-capability bits for the given display. 


Register Description 
AX Set to 170AH to specify this function 
DX Set to the GDI information index 


Return Values 


On return, AX contains the integer value of the desired item. 


Comments 


The implied hDC for this call will be for the display. 


Identify WinOldApVersion 


This function returns the version number of the current old-application 
support module, winoldap.mod. 


Register Description 


AX Set to 1700H to specify this function 
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Return Values 


On success, the function returns the major version number in register AL 
and the minor version number in register AH. 


On failure, it returns 1700H in register AX. 


If the function fails, then Clipboard functions are not available in this ver- 
sion of winoldap.mod. 


OpenClipboard 

This function attempts to open Clipboard. 

Register Description 

AX Set to 1701H to specify this function 
Return Values 


If Clipboard is already open, the function returns register AX equal to 
zero. 


SetClipboardData 


This function fills Clipboard with the specified data. 


Register Description 

AX Set to 1703H to specify this function 

DX Set to the clipboard format supported by Win- 
OldAp 

ES:BX A pointer to the data 

SsiICX Set to the size of the data 


Return Values 


If data are copied into the allocated memory, this function returns register 
AX not equal to zero. 


If on return AX is zero, an error has occurred. 
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Comments 


WinOldAp should call ClipboardCompact prior to this to determine if 
the data can be accommodated in memory. 


13.2 Structures 


These structures mimic the actual Windows structures, with one major 
difference: instead of including a handle or pointer to other memory con- 
taining the actual data, the data follows the structure. The structure 
information now behaves like a header prefacing the data. 


Bitmap structure: 


bmType DW c salways zero 

bmWidth DW ig swidth of bitmap in pixels 
bmHeight DW id sheight of bitmap in raster lines 
bmWidthBytes DW ? tbytes/raster line 

bmPlanes DB fs :# of color planes in the bitmap 
bmBitsPixel DB ? 7# of adj color bits to def pixel 
bmBits DQ ? spoints to byte following bmHigDim 
bmWidDim DW e swidth of bitmap in 0.1 mm units 
bmHigDim DW c sheight of bitmap in O.1 mm units 
BitmapData ;the actual data 


MetaFilePict structure: 


mm DW ig *mapping mode 
xExt DW e 7x extent 

yExt DW Fg 7y extent 
MetaFilePictData sthe actual data 


13.3 OEM Character Sets 


In Windows, the Clipboard and Windows applications use the ANSI char- 
acter set. In the DOS world, applications use the native (or OEM) charac- 
ter set of the PC they are executing on. For example, the Vectra uses IBM 
PC-8 and the HP150 uses Roman-8. The OEM and ANSI character sets 
usually contain a fair amount of overlap in contents. Using the Windows 
Clipboard and the Mark /Copy/Paste technique, you can easily transfer 
text between applications. 
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When data is copied from a DOS application (either level 1 or level 2) into 
Clipboard, a conversion to the ANSI character set is automatically per- 
formed. OEM characters that are copied into Clipboard are automatically 
converted to the ANSI character set. 


This conversion is fine if the intended destination is a Windows applica- 
tion that accepts only ANSI characters. Also, a conversion would have to 
be performed eventually. However, if the intended destination is another 
DOS application, characters that would have made sense to the receiving 
application may be garbled in transit. 


WinOldAp Version 2.0 remedies this situation. When a DOS application is 
started, WinOldAp registers a new clipboard format, CF_OEMText. If 
data is copied into Clipboard, WinOldAp sets the data in Clipboard in two 
formats: CF_ TEXT and CF_ OEMText. Then, if a Windows application 
requests data, CF_ TEXT will be available. If a DOS application requests 
data, WinOldAp will first get CF_OEMText, if it is available. Otherwise, 
it will get CF_ TEXT and convert from ANSI to OEM as before. 


13.4 Microsoft Word Support in WinOldAp 


Currently, Microsoft Word used with EGA allows the background screen 
color to be changed. When used in conjunction with Windows, the back- 
ground color sometimes cannot be restored in Word after a context switch. 
This is because Word bypasses the EGA BIOS to do its own palette 
management. Upon context switching, Windows tries to restore the state 
to the previously saved state, but having no knowledge of Word’s manipu- 
lation of the color palette, it fails to restore the proper context. Word pro- 
vides an answer to this problem with the undocumented keystroke combi- 
nation SHIFT+CTRL+\, which resets the color palette to the setting main- 
tained by Word. All that is required is to put this keystroke combination 
into the keyboard buffer upon context switch to make Windows EGA con- 
text switching work properly with Word. 


There are three ways in which this can be done. The first method involves 
modifying word.pzfin such a way that WinOldAp recognizes this applica- 
tion and sets the SHIFT- and CONTROL-key bits in the system RAM and 
inserts the \ key in the keyboard buffer when context switching back to 
Microsoft Word. The second method is to write a shell to communicate 
with WinOldAp and send a macro with the required key combination on 
context switch. The latter method is more elegant. The third, very simple, 
solution could be to detect Word from WinOldAp before a context switch 
and then set the SHIFT- and CONTROL-key bits and insert the \ keycode in 
the keyboard buffer before returning control to Word. 
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This problem is resolved with Word-specific coding in WinOldAp. This 
task is performed in two steps: 


1. Detecting Word from WinOldAp before a context switch 


During start-up, Word tries to communicate with any cooperating 
Terminate and Stay Resident (TSR) programs that are present 
through an undocumented int 16H with AX = 5500H. If any 
cooperating TSR is present, it responds with AX = 4D53H (ASCII 
"Ms"), then Word assumes that a TSR is present and that it will 
handle the keyboard. If this is not the case, Word installs its own 
keyboard int 9H and int 16H. Using these new interrupt routines, 
Word gets the keyboard status, with the scan code in AH, the 
ASCII code in AL, and the correct shift state in BL. By monitoring 
int 16H for AX = 5500H during context switch back to WinOldAp, 
WinOldAp could find that Word is present and requires the special 
treatment. . 


2. Screen Redraw of Word 


Word provides a screen-redraw facility that a cooperating TSR 
could use. This is the facility WinOldAp should use to redraw the 
Word screen. 
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The Macintosh Programmer’s Introduction to Windows 


A.1 Introduction 


This appendix is intended to introduce the Macintosh programmer to the 
Microsoft Windows environment for DOS personal computers. It provides 
a broad overview of the Windows architecture and of the similarities and 
differences between writing applications for the Macintosh and writing 
applications for Windows. While every effort has been made to ensure the 
accuracy of this document, Microsoft does not warrant that Windows 
operates as it is described here. 


The Microsoft Windows API is similar to the Macintosh API, since both 
are descendants of the seminal Graphical User Interface work done at 
Xerox PARC. There are a number of similarities between them because 
they have the similar goals of providing graphics and graphical user inter- 
face tools to the applications that use them. There are some differences, 
motivated by the different environments for which they are designed and 
by differences in design goals. 


The central similarities are as follows: 


Windows provides a set of graphics primitives in its graphics device 
interface (GDI) that are close to those of Quickdraw. 


Windows controls (text /edit, radio buttons, check boxes, and so 
forth) provided by the user-interface functions are much like those 
of the Macintosh Control Manager. 


Windows provides similar resource-management capacity to that of 
the Macintosh. Resources such as menus and dialogs, are dynami- 
cally loaded and discarded. This capacity allows the quick creation 
of Windows applications for different countries, including the crea- 
tion of European and Far Eastern applications using the same 
application code. 


Windows manages memory for both data and code in a manner 
similar to that of the Macintosh Memory Manager and Segment 
Loader. Movable data segments and dynamic loading of code seg- 
ments are key functions of the Windows kernel. 


The basic structure of typical Windows application code is similar 
to that of the Macintosh. There is an initialization section, and 
then the application goes into a “forever” loop, getting and pro- 
cessing messages from Windows. All of a Windows application’s 
input comes in the form of messages. Typical messages are the 
WM_ PAINT message indicating that the applications window is to 
be painted, and the WM_ CHAR message indicating that an ANSI 
character has been entered by the user. 


Windows applications may currently be developed using Microsoft 
C Version 3.0 or later, Microsoft Pascal Version 3.3 or later, or the 
Microsoft Macro Assembler Version 3.0 or later. Windows 
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applications may also use functions written in Microsoft Fortran 
Version 3.3 or later, although the interface to Windows should be 
through C, Pascal, or Assembler. Microsoft is interested in other 
languages being adapted to support Windows. 


The central differences between the Macintosh and Windows are as fol- 
lows: 


e Windows is a multiple-application environment. This means that 
smaller applications, which within the Macintosh would be desk 
accessories, are built as normal Windows applications that just 
happen to be small. None of the Macintosh’s desk accessory limita- 
tions are placed on these applications. 


e Windows applications run on the entire set of DOS machines that 
run Windows. This includes virtually all DOS machines from major 
manufacturers. This display-device independence necessitates a 
a sophisticated approach to graphics than that of the Macin- 
tosh. 


A.2 Kernel Functions 


Windows has the following kernel functions: 


e Task management 
e Code management 
e Data-space management 


e Resource management 


The Windows kernel enhances the functionality of the DOS operating sys- 
tem kernel that runs underneath it. The primary function area preserved 
from DOS for use by Windows applications is the file system. Task 
management, memory management, and all non-file input/output opera- 
tions are provided by the Windows kernel. 


A.2.1 Task Management 


Windows is a non-preemptive multitasking system. This design was chosen 
to maximize the system’s performance given its basis in DOS, a single- 
tasking operating system. Non-preemption means that control is passed 
from application to application voluntarily. Generally, an application runs 
from the time it gets an input message until it asks for another one. The 
exceptions to this are interrupts from the hardware, which are preemptive. 
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Non-preemption implies that a given application may continue to run 
indefinitely and never allow another to run. To avoid this, an application 
should explicitly check its message queue frequently to allow another 
application to take control. The calls used to implement this are described 
in the Microosoft Windows Programmer’s Reference. For comparison, the 
Macintosh is primarily a single-tasking system that allows the installation 
of Desk Accessories (mini-applications that periodically are given control 
by the operating system). 


A.2.2 Code Management 


The Windows kernel manages code segments in much the same way as the 
Segment Loader does in the Macintosh. As on the Macintosh, code seg- 
ments are movable and discardable. A difference is that the default state 
for Windows segments is discardable, which is the equivalent to being 
Unloaded in Macintosh terminology. This can be changed at link time or 
at run time. The kernel maintains a list of discardable segments and call 
counts to allow segments to be discarded on a least-recently-used (LRU) 
basis. This capacity allows Windows to provide the best performance to 
the user for a given usage pattern for a given mixture of applications dur- 
ing a given session. 


A.2.3 Data-Space Management 


Windows provides a double-indirected data-space (heap) manager that is 
similar to that of the Macintosh. There are some modifications to adapt to 
the Intel segmented architecture rather than the linear address space of 
the Motorola family. There are also some design changes to support the 
Windows multiple-application, multiple-instance architecture. 


Windows applications have two areas in which to create data objects, in 
addition to automatics on the stack: their local heap—or DS, and the glo- 
bal heap. The decision to allocate a given object in one or the other of 
these is based on a trade-off of speed against space. Windows manages the 
location of the local heap, and accessing a local object is faster because it 
requires only the loading of a 16-bit pointer (offset into a segment). The 
total of a Windows application’s statics, local-heap objects, and (nor- 
mally) its stack must not exceed 64K bytes. The only limitation on the size 
of global objects is that a single object may not exceed 64K bytes. The 
additional overhead for accessing global objects is necessary because these 
objects are accessed through 32-bit pointers, which take more time to set 


up. 


All the standard memory-management operations allocate, reallocate, free, 
and so forth are available in local and global variants. Either the local or 
global heaps may be compacted, and it is possible to determine the size of 
the largest available block of memory in either of them. Data objects in 
either the local or global heap can be marked as movable or fixed. In the 
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current version of Windows, all the global memory objects must fit into 
system memory. 


A.2.4 Resource Management 


Windows provides resource management in much the same fashion as the 
Macintosh does. Resources such as menus, dialogs, fonts, and strings are 
loaded on demand. Application resources may be marked as “preload” in 
order to be loaded at the same time as the application. Bitmaps may be 
included in menus and dialog boxes. It is possible (and strongly suggested) 
that the text of an application be separated into resource files. This allows 
for quick editing and for speedy internationalization. Updating an applica- 
tion to reflect a change in the resource file requires only running the 
Resource Compiler, re. Windows also provides a Dialog Editor that auto- 
mates the creation of dialog boxes. 


A.3 GDI Functions 


Windows has the following GDI functions: 


e Region manipulation 

e Device context 

e Font management 

e Mapping modes 

e Metafile support 

e Use of color 

e Graphics primitives 

e Printing 
The Windows GDI provides a set of functions that will be familiar to 
Macintosh programmers. Nearly all of the Quickdraw graphics operations 
are available to Windows applications. The key extensions to the Quick- 
draw function set result from Windows being designed to run on DOS 


et eg with different display resolutions, aspect ratios, and color capa- 
bilities. 
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A.3.1 Region Manipulation 


One of the most important functional areas for graphics-intensive Macin- 
tosh applications 1s region-manipulation. Windows provides a full set of 
region manipulation operators: Union, Intersection, Inversion, Outline, 
and so forth. These GDI operations are hand-coded in assembly language 
to achieve the highest performance possible. 


A.3.2 The Device Context 


The key to using GDI is the device context (DC). The DC is the Windows 
analog to the Macintosh Grafport. The DC 1s the logical location of all the 
information about drawing on a particular display surface. Included in the 
DC is the information about the physical device, the clipping region, the 
visible region, the current Brush, Pen, and Font, the mapping information, 
and so forth. Some of the information contained in a DC is available for 
use by applications, and some of it is Windows’ private information. All 
graphics functions require a DC for operation. Windows passes a handle to 
a DC (hDC) to an application when the application is asked to paint its 
display area. Applications wanting to print ask that a DC be created for 
the destination device and pass that DC to graphics operations to create 
the printed image. As they can on the Macintosh, applications can create 
output on a printer without displaying it on the screen. 


A.3.3 Font Management 


Windows provides an excellent set of font tools. Fonts are resources avail- 
able to all applications. It is possible for output-device vendors to sell 
Windows fonts that are screen representations of the fonts available on 
their device. 


The run-time creation and selection of fonts uses the Font Mapper. An 
application asks Windows, for a particular DC, what the nearest font is to 
a specified ideal font. Windows chooses among the fonts available for the 
device specified for that DC through a weighted system that considers 
several font characteristics. The font choice mechanism is explained in 
greater detail in the Microsoft Windows Programmer’s Reference. 


Windows will scale bitmapped fonts to integral pixel multiples to meet an 


application’s font requirements. Non-integral scaling is provided for vector 
fonts. 
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A.3.4 Mapping Modes 


Mapping modes are the key to the device independence of GDI. They allow 
applications to specify and interpret positions and distances used in 
graphics operations in a flexible way that does not vary from device to 
device. Mapping modes can be changed at will for a particular window. 
Mapping modes can be described in three groups: identity, real, and 
theoretical. 


The identity mode allows applications to work in screen coordinates. This 
is called the text mapping mode. Text mode allows coordinates to be 
specified in pixels. 


Real mapping modes allow coordinates to be specified in physical measure- 
ments. A typical use of a real mapping mode would be to draw a one-half 
inch square two inches down and one inch from the upper-left-hand corner 
of a window. Real mappings can be further subdivided into English, metric 
and typographical groups. In the English group, measurements are In 
inches. In the metric group, there are high- and low-resolution millimeter- 
based mapping. In the typographical group, coordinates are interpreted in 
twips, twip being one-twentieth of a point. 


There are two theoretical mapping modes: anisotropic and isotropic. 
Anisotropic mapping allows arbitrary scaling that is independent in the 
horizontal and vertical directions. It is useful for drawing figures to fill a 
window of arbitrary size. Isotropic mapping mode is similar to the aniso- 
tropic mode except that isotropic mappings provide a space with a virtual 
1:1 aspect ratio. This is useful for scaling figures to fill an area so circles 
remain circular, where the anisotropic mapping mode would allow an oval 
to be painted. 


A.3.5 Metafile Support 


Windows supports the creation of metafiles to record a series of graphics 
operations, They are a more general version of the Macintosh’s Picture 
format. There is also an even closer Windows equivalent to Picture, made 
by adding absolute size information to the metafile format. Once a 
metafile format is created, a DC is returned to the creator, and commands 
are a to the metafile by calling graphics routines to operate on this 
metaiile. 


A.3.6 Use of Color 


Windows also expands on the capabilities of the Macintosh by adding 
device-independent support for color. An application can choose a color 
for a pen or brush by inquiring, for a particular DC, which color available 
on the device is closest to an ideal color specified by a 24-bit RGB triplet. 
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Applications may also ask that the available colors for a DC be enumer- 
ated. This allows an application to ask the user in a dialog box to choose a 
background color, while displaying the set of available colors. 


A.3.7 Graphics Primitives 


Windows provides a set of graphics primitives that follow closely those of 
Quickdraw. The standard Line, Ellipse, Rectangle, RoundRect, and so 
forth are available. Like the Macintosh, Windows provides a versatile, 
high-performance BitBit operation. Windows supports all of the 256 possi- 
ble three-operand raster operations for BitBit. There is also a scaling Bit- 
Bit available, called StretchBit. The Windows display drivers are optim- 
ized for the highest possible performance from a given device. 


A.3.8 Printing 


As mentioned previously, printing from a Windows application is a trivial 
extension of creating graphics on a bitmapped display device. The applica- 
tion simply requests that a DC be created for a particular display device 
attached to a specified machine port. Then, using that DC, the application 
performs the desired graphics operations. 


Windows is flexible and powerful in its ability to mix device fonts and bit- 
mapped graphics on a page of text. This ability will become increasingly 
valuable as laser printers become more common in the personal computer 
environment. 


The spooling of the output is handled entirely by Windows, without inter- 
vention by the application creating the print request. Other Windows 
applications continue to run while the Spooler application is running. 
Maintenance of the print queue is also handled by the spooler, and the 
user may reorder or cancel jobs in the print queue. 


A.4 User-Interface Functions 


Windows has the following user-interface functions: 


e Controls 
e Dialogs 
e Chipboard 


e Messages 
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e Menus 
e Input-queue management 


e Keyboard 


A.4.1 Controls 


Windows provides a set of controls that are similar to those of the Macin- 
tosh Control Manager. Static text and text-edit controls, radio buttons, 
check boxes, list boxes, grouping boxes, scroll-bar controls, and so forth, 
as well as user-definable controls that merely provide hit-testing for a 
region are all available. There are some extensions to Macintosh control 
functionality, particularly in the area of keyboard use with controls. All 
the Windows controls are operable using only the keyboard. This is 
because most DOS personal computers, such as the IBM Personal Com- 
puter, are sold without a mouse. Making Windows operate without a 
mouse broadens its market by lowering the entry cost. 


A.4.2 Dialog Boxes 


Windows dialog boxes are constructed from controls in much the same 
way that they are built on the Macintosh. The Microsoft Windows 2.0 

Software Development Kit includes a dialog editor that speeds the con- 
struction of dialog boxes. 


A.4.3 The Clipboard 


Data exchange is an important strength of Windows and is an example of 
the Microsoft philosophy of appropriate integration. As on the Macintosh, 
a clipboard is the means by which data is transferred from application to 
application, and there is a Windows Clipboard application that allows the 
user to view the data being transferred. A key advantage of the Windows 
multiple-application approach is that both the donor and recipient of 
data, as well as any number of other applications, may be running and 
sharing the screen during a data-exchange operation. 


There are several predefined formats for data transfer, and Windows 
allows groups of cooperating applications or several instances of an appli- 
cation to define their own private format for transfer through Clipboard. 
The predefined formats include text, bitmaps, Windows metafiles, Micro- 
Dl : —— Link (SYLK), and Software Arts Data Interchange Format 
DIF). 


Applications that donate data in a private format to Clipboard may be 


asked to change the data into a readable form. This allows the contents of 
Clipboard to be viewed no matter what the data type. 
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The set of Clipboard operations is similarly extensible. The predefined 
operations include Send Current Selection, Append, and Replace Selection, 
among others. 


A.4.4 Messages 


As with the Macintosh, after the initialization of a Windows application is 
complete, the application polls for input messages and processes them as 
they become available. The message is the Windows analog to the Macin- 
tosh “event.” Message processing continues until a message indicates that 
the application should terminate. The message-passing architecture of 
Windows is general and is used to pass information between all of the 
processes in the system. 


All application input from the user and the environment comes in the form 
of messages. All mouse tracking, character input, timer notification, data 
exchange requests, and so forth come through the message mechanism. 


Because Windows can operate with several applications at one time, it has 
a capability the Macintosh does not have: the ability to pass messages 
between applications. The PostMessage function allows an application to 
asynchronously send a message and continue. The SendMessage function 
— an application to transmit a message and wait until the recipient 
replies. 


The generality of the message mechanism, both in versatility of message 
semantics and in inter-application communication, allows for sophisti- 
cated cooperating applications. A prime example of this capability is a 
hot-link between a communication program, a spreadsheet, and a charting 
program. 


A.4.5 Menus 


Like the Macintosh, Windows is flexible in the creation of menus. Menu 
structure is defined in a resource file, and menus are loaded dynamically. 
Windows menus can contain bitmaps. | 


From the user’s point of view, Windows menus are also much like those of 
the Macintosh. They pull down by moving the mouse cursor onto the 
desired item and clicking. In Windows, menus can be pulled down by using 
a keyboard instead of a mouse. 
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A.4.6 The Keyboard Interface 


Because Windows is designed to run on a system without a mouse, great 
care has been taken to ensure that all Windows functions can be operated 
efficiently with the keyboard. Menu selections can be made with only three 
keystrokes. All of the dialog-box functions are accessible from the key- 
board with a minimum of keystrokes. All Windows applications written by 
Microsoft are and will be usable without a mouse. 


A.5 Standard Preemptive Drivers 


Windows provides two exceptions to the non-preemptive multitasking 
rule: asynchronous communication and sound support. These exceptions 
are necessary given the nature of the tasks that they perform. They are 
present in standard Windows drivers in all adaptations of Windows to a 
particular machine. 


A.5.1 Asynchronous-Communications Support 


The Macintosh provides communication capabilities to applications. Win- 
dows has similar capabilities on the DOS machines on which it runs. Win- 
dows provides a device-independent mechanism for interrupt-driven back- 
ground serial communication. Windows functions can open and close a 
communication port, set the communications parameters, set a buffer size, 
set up flow control mechanisms that are then maintained by the driver, 
describe to Windows what types of events should be reported to the appli- 
cation, and provide other low-level communications support for Windows 
applications. 


A.5.2 Sound 


The Macintosh has excellent sound capabilities in its hardware and pro- 
vides a strong interface to them through its software. The sound hardware 
available on most DOS machines is inferior to the Macintosh’s. Windows 
provides a programmable, interrupt-driven, background sound capability. 
The sound driver is similar in capability to that of IBM’s BASICA or 
Microsoft’s GW-BASIC. It allows repetition of musical notes or phrases, 
changing keys and tempo, and other alert and entertainment functions. 
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A.6 A Simple Windows Application 


This section provides source code for two versions of a simple graphics 
application. This application, called Shapes, allows the user to choose a 
simple shape, such as a rectangle, square, or ellipse, to fill the application’s 
area on the screen (the “content” in Macintosh terms, the “client area” in 
Windows terms). 


A.6.1 Shapes for the Macintosh 


The Macintosh Version of the graphics application was written using 
Megamax C Version 1.0. The only change from the released version is that 
the several include files have been combined into two, combined.h and 
qdvars.h. This is just a convenience. 


/* This is a version of the Shapes program from the 
Microsoft Windows Programmer's Guide that has been 
functionally converted to the Macintosh. Copyright 1985, 
Microsoft Corp. «/ 


#include <combined.h> /xcombined.h is all of the include 
files for Megamax C except qdvars.h 
which is included later in MAIN() */ 


#define CLEARITEM 1 
#define ELLIPSEITEM 2 
#define RECTANCLEITEM 3 
#define STARITEM 4 
#define TRIANGLEITEM 5 


#define lastmenu 4 
#define applemenu 1 
#define filemenu 256 
#define editmenu 257 
#define shapesmenu 258 


menuhandle mymenus [lastmenutl1];> 

rect screenrect, dragrect, prect; 

boolean doneflag, temp, infoactive; 

eventrecord myevent; 

int code, refnum; 

windowrecord wrecord, infowrecord; 

windowrecord s#mywindow, *«whichwindow, *xinfowindow; 
int themenu, theitem, currentshape = 1; 


/* The graphics drawn into the content area are stored 


* as a group of Macintosh pictures, the handles to 
* which are kept in the array "picarray". 


*/ 
pichandle picarray [6]; 
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/* In this simple example, we have not included a 
* resource file for the menus, but instead build them 
* at run-time using this function. 


/ 
setupmenus () 


int i; 

char appletitle[2]; 
initmenus (); 

appletitle[O] = applesymbol; 
appletitle[1] = 0; 


mymenus [1] = newmenu (applemenu, ieee 
appendmenu (mymenus [1], "About Shapes...;- (" 

addresmenu (mymenus[1], "DRVR"); 

mymenus [2] = newmenu (filemenu, "File"); 

appendmenu (mymenus [2], "Quit"); 

mymenus [3] = newmenu(editmenu, "Edit") ; 

appendmenu (mymenus [3], " (Undo; (-:; (Cut; (Copy: (Paste"); 
mymenus [4] = newmenu(shapesmenu, “Shape"); 


appendmenu (mymenus [4], 
"Clear/C;Ellipse/E;Rectangle/R;Star/S;Triangle/T") ; 


for (i = 1; i <= lastmenu; itt) 
insertmenu (mymenus [i], 0); 
drawmenubar (); 


} 


docommand (themenu, theitem) int themenu, theitem; 


char name[256]; 
int i: 
switch (themenu) { 


case applemenu: 
if (theitem == 1) /+* This is the “About Shapes" items/ 


setrect (&screenrect, 50,100, 462, 300) ; 
infowindow=newwindow (&infowrecord, &screenrect, 

1, 3, (windowptr) -1, 1, (long) 1); 
infoactive=1; 


rt tf 
é 


else { 
getitem(mymenus[1], theitem, name); 
refnum = opendeskacc (name); 


} 

break; 

case filemenu: a 
doneflag = 1; ey 
break; 

case editmenu: 


systemedit (theitemt1l) ; 
break; 
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case shapesmenu: 


/* Set the current shape, clear the content area, 
* and indicate that the content area must be redrawn. 


*/ 


setport (mywindow) ; 

currentshape = theitem; 

eraserect (&mywindow->port.portrect) ; 
invalrect (&mywindow->port.portrect) ;: 
break; 


} 


hilitemenu (0) ; 


main () 


#include <qdvars.h> 
rect windowrect, mypicframe, myinnerframe, noscrollrect; 
int i; 


/* These are standard Macintosh initialization steps. +*/ 


initgraf (&theport) ; 
initfonts (); 

flushevents (everyevent, 0); 
initwindows ()? 
setupmenus (); 

theinit(); 

initdialogs (NULL) ; 
initcursor (); 


setrect (kscreenrect, 4, 40, 508, 338); 

setrect (&dragrect, 4, 24, screenrect.a.right - 4, 
screenrect.a.bottom - 4); 

infoactive = doneflag = 0; 


/* Set up pictures for later display, storing their handles 


into the picarray. Pictures are the standard Macintosh way 
to store scalable graphics images, and use the equivalent 


is an arbitrary scaling in both x and y dimensions to fill 


* 
* 
* of the Windows GDI mapping mode called anisotropic, which 
* 

* a destination rectangle. 
setrect (&mypicframe, -10, -10, 110, 110); 
setrect (&myinnerframe, 0, 0, 100, 100); 


picarray[1] = openpicture (&mypicframe) ; 
closepicture(); 


picarray[2] = openpicture (&mypicframe) ; 


frameoval (&myinner frame) ; 
closepicture(); 
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picarray[3] = openpicture (&mypicframe) ; 
framerect (&myinner frame) ; 
closepicture(); 


picarray[4] = openpicture (&mypicframe) ; 
moveto (100, 25); 

lineto(O, 25); 

lineto (80, 100); 

lineto(50, 0); 

lineto(20, 100); 

lineto (100, 25); 

closepicture(); 


picarray[5] = openpicture (&mypicframe) ; 
moveto (0, 100); 

lineto (100, 100); 

lineto (50, 0); 

lineto(O, 100); 

closepicture(); 


/* Open the application's only window. +«/ 


mywindow = newwindow(&wrecord, &screenrect, “Pick a Shape", 
1, 0, (long) -1, 0, (long) 0); 
setport (mywindow) : 


/* This is the standard Macintosh event loop. */ 


do { 

systemtask (); 

temp = getnextevent (everyevent, &myevent) ; 
switch (myevent.what) { 


case mousedown: 
if (infoactive) { 
closewindow (infowindow) ; 
infoactive=0; 


else { 
long lTemp; 
int i; 


code = findwindow (&myevent.where, &whichwindow) ; 


switch (code) { 


case inmenubar: 
docommand (menuselect (&myevent.where) ) ; 
break: 


case insyswindow: 
systemclick (4myevent, whichwindow) ; 
break; 


case indrag: 
dragwindow (whichwindow, &myevent.where, 
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&dragrect) ; 
break; 


case ingrow: 

setport (mywindow) ; 

lTemp=growwindow (mywindow, &myevent.where, 
&screenrect) ; 

i = hiword(lTemp) ; 

sizewindow (mywindow, (int) lTemp, i, FALSE); 

eraserect (&mywindow->port.portrect) ; 

invalrect (&mywindow->port.portrect) ; 


break; 
case incontent: 
if (whichwindow != frontwindow()) 
selectwindow (whichwindow) ; 
break; 


break; 


case keydown: 
case autokey: 


/* This implements the command-key shapes commands. +/ 


if ((mywindow == frontwindow()) && (myevent.modifiers & 
256L) ) 
docommand (menukey ((char) myevent.message)); 
break; 


case activateevt: 


if ((windowrecord *) myevent.message == mywindow) { 
setport (mywindow) ; 
drawgrowicon (mywindow) ; 


break: 


case updateevt: 
if (infowindow == (windowptr) myevent.message) { 

setport (infowindow) ; 

textfont (0); 

beginupdate (infowindow) ; 

moveto(10, 50); 

drawstring("Shapes from the Microsoft Windows 
Programmer's Guide"); 
endupdate (in fowindow) : 


else { 
setport (mywindow) ; 
beginupdate (mywindow) ; 
noscrollrect.a.left = 
mywindow->port.portrect.a.left: 
noscrollrect.a.top = 
mywindow->port.portrect.a.top; 
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noscrollrect.a.right = 
mywindow->port.portrect.a.right - 16; 
noscrollrect.a.bottom = 
mywindow->port.portrect.a.bottom - 16; 
drawpicture (picarray[currentshape], &noscrollrect) ; 
drawgrowicon (mywindow) ; pak, 
endupdate (mywindow) ; _ 


} 
break; 
I 
while (doneflag == 0); 


for (i = 1;i <= S;itt) 
killpicture(picarray [i]): 
} 


A.6.2 Shapes for Windows 


The second version of the graphics application is the Windows version. It 
is compiled using the Microsoft C Compiler, the Microsoft Segmented 
Linker link4, and the Microsoft Make utility, make: 


/* This is shapes.rc x / 
/* Command IDS *+/ 


tdefine IDDELLIPSE Ox0101 
#define IDDTRIANGLE 0x0102 


#define IDDSTAR Ox0103 
#define IDDCLEAR 0x0104 
#define I[DDRECT Ox0105 


/* String table constants +/ 


#define IDSNAME 100 
#define IDSABOUT 200 
#define IDSTITLE 300 
#define ABOUTBOX 1 /* "About' dialog box ID +«/ 


#include "windows.h" #include “shapes.h" 
shapes ICON shapes.ico 


shapes MENU BEGIN 
POPUP "Shape" 


BEGIN 
MENUITEM "Clear*c"™ , IDDCLEAR 
MENUITEM "Ellipse*E" , IDDELLIPSE Se 
MENUITEM "Rectangle“R", IDDRECT 
MENUITEM "Star“*S" , LDDSTAR 
MENUITEM "Triangle*T" , IDDTRIANGLE 
END 


END 
shapes ACCELERATORS BEGIN 
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"Cc", IDDCLEAR 

"“E", IDDELLIPSE 

"*“R", IDDRECT 

"“S", IDDSTAR 

"ep", IDDTRIANGLE 
END 


ABOUTBOX DIALOG 22, 17, 144, 75 STYLE WS_POPUP | WS_DLGFRAME 


BEGIN 

CTEXT "Microsoft Windows" “1 37s. 55. 68.98 

ICON "shapes" -1, 9, 23, 0, O 

CTEXT “Shapes application" -1, 0, 14, 144, 8 

CTEXT “Version 1.01" -1, 38, 34, 64, 8 

CTEXT “Copyright (c) 1985, Microsoft Corp." -1, 5, 
47, 132, 9 

DEFPUSHBUTTON "Ok" IDOK, 53, 59, 32, 14, 
WS_GROUP 

END 

STRINGTABLE BEGIN 

IDSNAME , "Shapes" 

IDSABOUT, "About..." 

IDSTITLE, "Pick a Shape" 


END 


/* This is shapes.c «/ 


/* shapes.c 
* Microsoft Windows Shapes Application 
* Premiere Edition, Copyright(c) Microsoft, 1985 


*/ 


#include "windows.h" 
#include “shapes.h" 
Static HANDLE hInst: 
static HANDLE hAccelTable; 
static int: 

cCurrentShape = IDDSTAR; 
FARPROC lpprocAbout; 

char *szAppName; 

char *szAbout; 

char *szWindowTitle: 
static POINT StarPoints[] = 


100, 75, 0, 75, 80, 0, 50, 100, 20, 0, 100, 75 
} 


long FAR PASCAL ShapesWndProc (HWND, unsigned, WORD, LONG); 

BOOL FAR PASCAL About (hDlg, message, wParam, lParam) HWND hDlg; 
unsigned message; 

WORD wParam; LONG 1]Param; 


{ 
if (message == WM_COMMAND) { 
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ShapesSetupDC (hWnd, hDC) HWND hWnd; 


EndDialog( hDlg, TRUE ); 
return (TRUE); } 

else if (message == WM_INITDIALOG) 
return (TRUE); 

else return (FALSE); } 


HDC hDC; 


{ 


} 


RECT ClientRect; 

SetBkMode (hDC, OPAQUE) ; 

SetROP2(hDC, R2_COPYPEN) ; 

GetClientRect (hWnd, (LPRECT) &ClientRect) ; 

SetMapMode (hDC, MM_ANISOTROPIC) ; 

SetWindowOrg(hDC, ~-10, 110); 

SetWindowExt (nDC, 120, -120); 

SetViewportOrg(hDC, 0, 0); 

SetViewportExt (hDC, ClientRect.right - ClientRect.left, 
ClientRect.bottom - ClientRect.top ): 


ShapesPaint (hWnd, lpps) HWND hWnd; 
LPPAINTSTRUCT lpps; 


{ 
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HDC hShapesDC; 
HBRUSH hbr, hbr0Old; 
HPEN hpen, hpenOld; 


ShapesSetupDC (hWnd, hShapesDC = lpps->hdc) ; 

if (lpps->fErase) { 
hbr = CreateSolidBrush (GetSysColor (COLOR_WINDOW) ) ; 
hbrOld = SelectObject (hnShapesDC, hbr); 
FillRect (nShapesDC, (LPRECT) &lpps->rcPaint, hbr); 
SelectObject (hShapesDC, hbrOld); 
DeleteObject (hbr) ; 

} 


hpen = CreatePen(PS_SOLID, 0, GetSysColor (COLOR_WINDOWTEXT) ) ; 
hpenOld = SelectObject (nShapesDC, hpen); 

SelectObject (hShapesDC, GetStockObject (NULL_BRUSH) ) ; 

switch (cCurrentShape) { 


case IDDCLEAR: 
break: 


case IDDRECT: 
DrawRect (hShapesDC) ; 
break; 


case IDDELLIPSE: a 
DrawEllipse (hShapesDC) ; 
break: 


case IDDTRIANCLE: 
DrawTriangle (hShapesDC) ; 
break: 
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case IDDSTAR: 
DrawStar (hShapesDC) ; 
break: 


t 
SelectObject (hShapesDC, hpenOld); 
DeleteObject (hpen) ; 

} 


DrawRect (hDC) HDC hDC; 
a! 
Rectangle (hDC, 0, O, 100, 100); 


DrawEllipse (hDC) HDC hDC; 
Ellipse (hDC, 0, 100, 100, QO); 


Drawlriangle(hDC) HDC hDC; 
{ 
MoveTo (hDC, 0, 0); 
LineTo(hDC, 100, 0); 


LineTo (hDC, 50, 100); 
LineTo (hDC, 0, O):; 


DrawStar (hDC) HDC hDC; 


Polyline(hDC, StarPoints, 6); 


ShapesCommand (hWnd, id) HWND hWnd; 


int id; 

{ 
HMENU hMenu = GetMenu (hWnd) ; 
CheckMenuItem (hMenu, cCurrentShape, MF_UNCHECKED) ; 
cCurrentShape = id: 
CheckMenulItem (hMenu, cCurrentShape, MF_CHECKED) ; 
InvalidateRect (hWnd, (LPRECT) NULL, TRUE); 

} 


int PASCAL WinMain (hInstance, hPrevInstance, lpszCmdLine, cmdShow) 
HANDLE hInstance, hPrevInstance; 

LPSTR lpszCmdLine:; 

int cmdsShow; 


MSG msg; 
HWND hWnd; 
HMENU hMenu:; 


/* Loading from string table «/ 
szAppName = (char *) LocalAlloc(LPTR, 10); 


szAbout (char *) LocalAlloc(LPTR, 10); 
szWindowTitle = (char *) LocalAlloc(LPTR, 15); 
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LoadString(hInstance, IDSNAME, (LPSTR) szAppName, 10); 
LoadString (hInstance, IDSABOUT, (LPSTR) szAbout, 10); 
LoadString(hInstance, IDSTITLE, (LPSTR) szWindowTitle, 15); 


if (thPrevInstance) 
if (!ShapesInit (hInstance) ) 
return (FALSE) ; 


else 


/* Copy the global instance variables from the previous 
* instance. 


*/ 


GetInstanceData (hPrevInstance, (PSTR) &hAccelTable, 
sizeof (hAccelTable) ); 


hWnd = CreateWindow((LPSTR)szAppName, (LPSTR) szWindowTitle, 
WS_TILEDWINDOW, 


0, /* x - ignored for tiled windows */ 
0, /* y - ignored for tiled windows */ 
O, /* cx - ignored for tiled windows +/ 
O, /* cy ~ ignored for tiled windows +*/ 
(HWND) NULL, /* no parent x / 
(HMENU) NULL, /* use class menu x / 
(HANDLE) hInstance, /* handle to window instance */ 
(LPSTR) NULL); /* no parameters to pass on x / 


hinst = hInstance; 
lpprocAbout = MakeProcInstance((FARPROC) About, hInstance) ; 
hMenu = GetSystemMenu (hWnd, FALSE); 
ChangeMenu (hMenu, O, NULL, 999, MEF_APPEND | MF_SEPARATOR) ; 
ChangeMenu (hMenu, 0, (LPSTR) szAbout, IDSABOUT, 
MF_APPEND {| MEF_STRING) ; 
ShowWindow (hWnd, emdshiow) 
UpdateWindow (hWnd) ; 


while (GetMessage((LPMSG) &msg, NULL, 0, 0)) { 
if ee hAccelTable, 
(LPMSG) &msg) == 0) { 
TranslateMessage ( (LPMSG) &msqg) ; 
DispatchMessage ( (LPMSG) &msg) ; 


exit (msg.wParam) ; 


int ShapesInit (hInstance) HANDLE hInstance; 


PWNDCLASS pShapesClass; 
pShapesClass = (PWNDCLASS) LocalAlloc(LPTR, 

sizeof (WNDCLASS) ) ; 
pShapesClass->hCursor = LoadCursor (NULL, IDC_ARROW) ; 
pShapesClass->hIcon = LoadIcon(hIinstance, (LPSTR) szAppName) ; 
pShapesClass->lpszMenuName = (LPSTR) szAppName; 
pShapesClass->hInstance = hInstance; 
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pShapesClass->lpszClassName = (LPSTR) szAppName; 
pShapesClass->hbrBackground = NULL; 


_pShapesClass->style = CS _HREDRAW | CS_VREDRAW; 


pshapesClass->lpfnWndProc = ShapesWndProc; 


if (!RegisterClass ((LPWNDCLASS) pShapesClass) ) 

return (FALSE); /*x Initialization failed +/ 
LocalFree ( (HANDLE) pShapesClass) ; 
hAccelTable = LoadAccelerators (hInstance, (LPSTR) szAppName); 


return (TRUE); 


/* Initialization succeeded +«/ 


LONG FAR PASCAL ShapesWndProc( hWnd, message, wParam, 1Param) 
HWND hWnd; 
unsigned message; 
WORD wParam; 

LONG 1Param; 


{ 


PAINTSTRUCT ps; 
RECT rect; 


HBRUSH hbr, hbrOld:; 


switch (message) { 


case WM_SYSCOMMAND: 
switch (wParam) { 


case [DSABOUT: 


DialogBox (hInst, MAKEINTRESOURCE (ABOUTBOX) , 
hWnd, lpprocAbout) ; 


break; 
default: 
return (DefWindowProc (hWnd, message, wParam, 
lParam) ); 
break; 
> 


break: 


case WM_CREATE: 
CheckMenuItem (GetMenu (hWnd), cCurrentShape, 
ME _CHECKED) ; 


break: 


case WM_PAINT: | 
BeginPaint (hWnd, (LPPAINTSTRUCT) &ps):; 
-. ShapesPaint (hWnd, (LPPAINTSTRUCT) &ps): 
EndPaint (hWnd, (LPPAINTSTRUCT) &ps); 


break: 


case WM_ERASEBKGND: 
GetClientRect (hWnd, (LPRECT) &rect); 
hbr = CreateSolidBrush (GetSysColor (COLOR_WINDOW) ) : 
hbrOld = SelectObject( (HDC) wParam, hbr); 
FillRect((HDC) wParam, (LPRECT) &rect, hbr); 
SelectObject ((HDC) wParam, hbr0Old); 
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DeleteObject (hbr); 
break; 


case WM_COMMAND: 
ShapesCommand (hWnd, wParam) ; 
break; : 


case WM_DESTROY: 
PostQuitMessage (0) ; 
break: . 


default: | 
return (DefWindowProc (hWnd, message, wParam, 1]Param) ); 
break: 


} 
return (OL); 
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